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PREFACE 


MANUAL OBJECTIVES 


The primary goal of this manual is to introduce P/OS physical I/O 
concepts, define Executive and I/O service routine protocol, describe 
system I/O data structures, and prescribe I/O service routine coding 
procedures. This information is in sufficient detail to allow you to: 


@ Prepare software that interfaces with the Executive and 
Supports a conventional I/O device. 


@ Incorporate the user-written software into an P/OS system. 
@ Detect typical errors that cause the system to crash. 


@ Use Executive service routines that an I/O service routine 
typically employs. 


@ Develop P/OS video applications. 


CAUTION 


Unless explicitly noted otherwise, all information in 
this manual is subject to change without notice. 


INTENDED AUDIENCE 


This manual is written for the senior-level system programmer who is 
familiar with the hardware characteristics of both the Professional 
300 Series and the device that the user-written software supports. 
The programmer should also be knowledgeable about DIGITAL peripheral 
devices and experienced in using the software supplied with an P/OS 
system. The manual neither describes general Executive concepts nor 
defines general system structures. The manual does describe I/0O 
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concepts, the Executive role in processing I/O requests, and some 
pertinent aspects of I/O processing done by DIGITAL-supplied software. 
Therefore, with a firm understanding of hardware characteristics and 
P/OS system software, a senior-level system programmer could attempt 
to write an I/O driver. 


STRUCTURE OF THIS DOCUMENT 


This manual has three types of information: conceptual, procedural, 
and reference. The following are abstracts of the chapters in the 
document: 


@® Chapter 1, "P/OS I/O Drivers," introduces terms and concepts 
fundamental to understanding physical I/O in P/OS, and 
describes the protocol that a driver must follow to preserve 
system integrity. It summarizes advanced driver features and 
P/OS capabilities helpful in becoming acquainted with overall 
Executive and driver interaction. 


@ Chapter 2, "Device Driver I/O Structures," continues’ the 
conceptual discussion begun in Chapter 1. It introduces on a 
general level the software data structures involved in 
handling I/O operations at the device level, examines typical 
arrangements of data structures that are necessary for 
controlling hardware functions, and presents a macroscopic 
software configuration that summarizes the logical 
relationships of the I/O data structures. 


@e Chapter 3, "Executive Services and Driver Processing," ends 
the conceptual presentation. It summarizes how an I/O 
request originates, how the Executive processes the request, 
and how a driver would use Executive services to satisfy an 
I/O request. 


@® Chapter 4, "Programming Specifics for Writing an I/O Driver," 
provides the detailed reference information necessary to code 
a conventional I/O driver. Included iS a_ summary of 
programming standards and _ protocol, an introduction to the 
programming facilities and requirements for both the driver 
data base itself and the executable code that constitutes the 
driver, and an extensive elaboration of the driver data base 
and of the driver code. 


@ Chapter 5, "Incorporating A User-Supplied Driver into P/OS," 
Supplies the procedural information that you need to assemble 
and build a loadable driver image, load it into memory, and 
make accessible the devices that the driver supports. Also 
included are a summary of the system generation dialogue 
concerning including user-supplied drivers and a description 
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of the loading mechanism and the diagnostic operations 
performed during loading. 


@® Chapter 6, "Debugging A User-Supplied Driver," summarizes 
software features provided to help you uncover faults in 
drivers and gives procedures to follow that might prove 
successful in isolating faults in drivers. 


@® Chapter 7, "Executive Services Available to An I/O Driver," 
gives general coding information relating to the PDP-11 and 
P/OS Executive service routines. 


® Chapter 8, "Sample Driver Code," shows the source code _ for 
the data base and driver of a conventional device and an 
excerpt of source code from a driver that handles’ special 
user buffers. 


@® Chapter 9, "The Professional Video Bitmap and Font 
Structure," provides reference information on the driver's 
control of Professional video hardware and software. It also 
describes the structure of the video fonts and lists the 
implemented fonts. 


® Appendix A, "System Data Structures and Symbol Definitions," 
lists the source code of system macro calls that define 
system device structures, driver-related structures, and 
system-wide symbolic offsets needed to access those 
structures. 


@ Appendix B, "Task Building and Cluster Libraries" is a 
collection of three documents describing overlaying task 
structures, cluster libraries, and task organization. 


@ Appendix C, "Files-ll On-Disk Structure Specification" 
describes the general-purpose file structure intended for use 
on medium and large-size PDP-1ll systems. 


@® Appendix D, "QIO Interface to the ACPs," describes the QIO 
level interface to the file processors (ACPs). 


ASSOCIATED DOCUMENTS 


Included in your P/OS Tool Kit documentation are documents that 
describe both the software and hardware on the system. The software 
documents are listed and described in the Tool Kit User's Guide (Order 
no. AA-N617D-TK). Consult this document for concise summaries of 
software-related publications. For information on hardware technical 
specifications, see the Professional 300 Series Technical Manual 


(Order no. EK-PC350-TM-0O01). 


Also, it is recommended that you refer to the P/OS Executive listings, 


which are published on microfiche. It is entitled Executive Listings 
and Maps, order number AH-CG61A-TK. 


ASSOCIATED FILES 


As mentioned in your installation guide, the directory [ZZPRIVDEV] on 
the PRODCL2 diskette contains several library and symbol table files, 
which are needed for writing privileged applications. The file 


README.TXT in the same directory contains further information about 
these files. 


Contrary to what is stated in the installation guide, you do not _ need 
"system manager privileges" to read these files on your Professional. 
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CHAPTER 1 


P/OS I/O DRIVERS 


Device drivers on P/OS are the primary method of interfacing the 
Executive's I/O subsystem with hardware attached to the computer. 
Most DIGITAL-supplied hardware is supported by drivers accompanying 
the system that the user’ receives. This chapter introduces the 
concept of device drivers and explains driver operations and features. 


1.1 VECTORS AND CONTROL AND STATUS REGISTERS 


Associated with a device contoller are device control and status 


registers. The addresses of these registers are determined by the 
physical slot in which the controller has been inserted, rather than 
the actual option module. A given controller may have up to 64. 


words of device registers as shown in Table 1-1. To provide a_ unique 
identification for controllers, a hardware ID is. expected to be 
present, and may be accessed at the first address within a given 
slot's device register address range. The bootstrap and diagnostic 
ROM examines each option slot and places the hardware IDs in a 
configuration table located at the top of physical memory. This table 
is referenced by PROLOD to resolve the hardware ID specified in the 
controller table (CTB) located in the driver's database. The table 
may also be accessed by the executive's WIMPS directive (See the 
Professional 300 Series System Reference Manual for further details of 
the directive arguments and table format.) Certain controllers are 
physically present on the motherboard. These devices have predefined 
device registers and are fully described in the Professional 300 
Series Technical Manual. 


VECTORS AND CONTROL AND STATUS REGISTERS 


Table 1-l: Option Slot Address Assignments 


Vector Vector 
Physical Logical address address 
Slot Slot Device Register Interrupt A Interrupt B 
Position Number Address Range ICSRA= ICSRB= 
17773206 ICSRA+4 
1 0 17774000-17774177 300 304 
2 ] 17774200-17774377 310 314 
3 Z 17774400-17774577 320 324 
4 3 17774600-17774777 330 334 
5 4 LTT TSO00=177 75777 340 344 
6 S 17775200-17775377 350 354 


System Peripheral Address Assignments 


Logical (ICSR= 17773202) 

Slot Device Register Vector 

Number Address Range Address Device type 

0 Not used 

1 17773500-17773506 200 Keyboard Receiver 

2 204 Keyboard Transmitter 

3 17773300-17773314 210 Comm. Port Rec./Trans. 
A, 214 Comm. Port Modem Status 
5 17773400-17773406 220 Printer port receiver 
6 224 Printer port trans. 

7 17773000-17773032 230 System clock 


Optionally, a controller may utilize one or two of the two-word areas 
associated with each slot, called interrupt vectors. A vector 
provides a connection between the device and the software that 
services the device. A vector allows a device to trigger certain 
software actions because of some external condition related to the 
device. When a device interrupts, the vector address is sent to the 
processor. The first word of the interrupt vector contains’ the 
address of the interrupt service routine for that device. The 
processor uses the second word of the vector as a new Processor Status 
Word. Thus, when the processor services the interrupt, the first word 
of the vector is taken as the new Program Counter (PC) and the second 
word is the new PS. 


VECTORS AND CONTROL AND STATUS REGISTERS 


Space is reserved on the PDP-11 for the interrupt vectors. This space 
is in the low part of Kernel I-Space. The vectors are considered to 
be in Kernel mode virtual address space and are thus mapped by the 
Executive. Because the interrupt vector is in Kernel space, the 
Executive receives control of the processor on every interrupt. 


1.2 SERVICE ROUTINES 


The service routine that is entered to process an interrupt is most 
frequently in the device driver. Device drivers vary in complexity 
depending on the capabilities of the type of device and the number of 
device units they service. 


Although linked into the Executive structures, a driver resides in 
memory outside the virtual address space of the Executive. An 
application can add or remove a driver by means of a callable "POSSUM" 
system routine. In addition, any driver not required for a period of 
time need not be loaded. The space normally occupied by the unloaded 
driver can hold user tasks or another driver. 


1.2.1 Executive and Driver Layout 


A device driver is a logical extension of the Executive that is not 
contiguous in physical memory with the Executive code. Active Page 
Registers (APRs)* 0 through 4 map the Executive, APR 7 is reserved to 
map the I/0 page, and APR 5 maps the driver. Therefore, a driver is 
by default restricted to the 4K words of space mapped by APR 5 unless 
it controls its own mapping with APR 6 to gain access to an extra 4K 
words. 


The virtual to physical mapping of a P/OS system is shown in Figure 
Las 


* Active Page Register is a term referring to the Memory Management 
register pair (Page Address Register (PAR) and Page Descriptor 
for information on hardware mapping and memory management. Refer to 
the RSX11M-Plus Task Builder Manual for a description of mapping and 
APR assignments by software. 
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Figure 1-1: Virtual to Physical Mapping for the Executive 


Virtual addresses 20K through 28K words (APR 5 and APR 6) are reserved 
to map drivers and privileged tasks in Kernel mode. (Although APR5 
and APR6 are reserved for drivers, the Executive maps only APR5- when 
it calls a driver.) Finally, virtual addresses 28K through 32K words 
(APR 7) map the I/O page. 


SERVICE ROUTINES 


Thus, a device driver is mapped with the Executive code and the I/O 
page. When a driver has control, it can access the device registers 
in the I/O page to perform its operations. While in system state, a 
driver has access to all the Executive service routines to help it 
process I/O requests. While in interrupt state, the driver must’ save 


and restore APR 6 (access to APR 6 is unrestricted when the driver is 
in system state). 


Because of the layout of the Executive and device drivers, many common 
functions related to I/O are centralized in the Executive as service 
routines. This commonality eliminates the inclusion of repetitive 
coding in each and every driver. Coding in each driver is therefore 
reduced to handling the specific functions of the device supported. 


1.2.2 Driver Contents 


A device driver consists of two parts. One part is the executable 
instructions of the driver itself. This part has the entry points to 
the driver. The entry points are those places where the Executive 
calls the driver to perform a specific action, and their addresses are 
established in the driver dispatch table (DDT). The table contains 
addresses of routines in a fixed order so that the Executive can enter 
the driver at the appropriate place for a given action. 


The other part of a device driver is the data structures forming the 
data base that describes the controllers and units supported by the 
driver. Two structures, the controller table (CTB) and the controller 
request block (KRB), describe the controller of the device being 
Supported. Because the CTB supplies generic information about’ the 
controller type, only one CTB need exist for each controller type on a 
system. The KRB holds information related to a specific controller 
and therefore each controller has its associated KRB. 


Three structures in the driver data base--the device control block 
(DCB), the unit control block (UCB), and the status control block 
(SCB)--describe the device as a logical entity. The DCB contains 
information related to the type of device, whereas the UCB holds 
information specific to an individual unit of the device. The SCB is 
used mainly to store data (driver context) concerning an operation in 
progress on the device unit. 


The driver data structures are tailored to the number of controllers 
on the system, the number of units attached to each controller, and 
the types of features the devices support. The structures increase in 
complexity as the number of supported features increases. 


EXECUTIVE AND DRIVER INTERACTION 


1.3 EXECUTIVE AND DRIVER INTERACTION 


The Executive and a driver interact by accessing and manipulating 
common data structures. An I/O activity typically begins when a task 
generates a request for input or output. The Executive performs 
preliminary processing of that request before it initiates the driver. 
This preliminary processing, called predriver initiation, is common 
for all drivers and eliminates a great deal of code from all drivers. 


In performing predriver initiation, the Executive accesses the driver 
data structures to assess the legality of the I/O request. For 
example, cells in the device control block (DCB) define the functions 
that the driver supports. If the function specified in the I/O 
request is not supported by the driver, the Executive need not call 
the driver. The driver is not aware of the I/O request. Therefore, 
the Executive calls the driver only when the predriver initiation 
warrants it. 


1.3.1 The Driver Process 


When the Executive does call the driver to process an I/O request, the 
driver begins I/O initiation. Once an I/O request is created, a 
driver process is initiated. The Executive has queued to the driver 
an I/O packet that must be processed to satisfy the request. 
Potentially there exist on the system as many driver processes as 
there are distinct units capable of being active simultaneously. 
(Moreover, some drivers supporting advanced features can have multiple 
I/O requests simultaneously active for a given unit. In this case, 
each active I/O request is part of a separate driver process. Refer 
to Section 1.4.3 for more information. 


Central to a full understanding of a driver and the I/O structure is 
the difference between a driver process and the driver code. The 
driver code, (which is pure instruction), invokes an Executive routine 
called SGTPKT to get an I/O packet to process. This activity 
generates data for the request being processed and the unit doing’ the 
processing. The driver process, once initiated, starts the proper I/O 
function, waits for a completion interrupt and performs any required 
data transfers. It then completes the I/O by specifying I/O status 
and requesting another I/O packet. This sequence of execution steps 
continues until the I/O queue is empty and the driver process 
terminates. 


Because a driver may be capable of servicing several I/O requests in 
parallel, it is possible that, for a single driver, many driver 
processes exist at the same time. However, there is only one copy of 
driver code. The driver process is reentrant code and the data that 
defines the state of the code is stored in the driver data base when 
the process is not executing (for example, when it is waiting for an 
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interrupt). The driver process executes driver code for a particular 
device type on behalf of a specific unit. If independent units of a 
particular device type are concurrently active, several driver 
processes are also active at the same time, each with its own set of 
data. 


1.3.2 Interrupt Dispatching and the Interrupt Control Block 


Once a driver starts an I/O function, it must await the I/O completion 
interrupt. When a device interrupt occurs, the processor pushes the 
current PS and PC onto the current stack and loads the new PS and PC 
From the device controller interrupt vector. By convention, the PS in 
the interrupt vector is preset with a priority of 7 and the number of 
the controller associated with the vector. (The controller number, 
which identifies a particular controller for a given controller type, 
is in the low-order four bits.) 


For a driver, the hardware cannot dispatch directly to the interrupt 
service routine in the driver because the driver is mapped outside the 
address space of the Executive. Therefore, some code in the Executive 
must initially handle the interrupt, load the mapping context of the 
driver, and dispatch to the proper driver. This code resides in the 
Executive in a structure called an interrupt control block (ICB). 
Figure 1-2 shows this mechanism. A common Executive coroutine, called 
interrupt save (SINTSI) is called from the ICB. The SINTSI coroutine 
saves two registers, R4 and R5, which are thereafter free for the 
driver to use. These registers are typically used by drivers to hold 
addresses of the data blocks containing unit status and _ control 
information, the SCB and UCB. (Most Executive routines assume these 
two registers hold pointers to the two structures. If the driver 
needs to use more registers, it saves them on the stack and restores 
them when it finishes.) Kernel APR 5 is then saved and the driver is 
mapped through APR 5 and called at the interrupt entry point. When 
the interrupt save coroutine returns to the driver, the driver runs at 
the interrupt level of the device that it is servicing and has two 
free registers that it can use. 


The driver may then run for a_eshort interval at the partially 
interruptable level. By convention, this interval should not exceed 
500 microseconds. When the driver finishes processing the interrupt, 
it may execute a RETURN instruction to transfer control back to the 
coroutine which gives control of the CPU to the next process.” 


* An Executive interrupt exit routine, SINTXT, exists to standardize 
the way a driver exits from an interrupt. This routine is executed by 
the SINTSI coroutine. Therefore, interrupt exit processing is 
effected via the "RTS PC" (RETURN) instruction. 
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Thus, the ICB actually contains a JSR instruction to an Executive 
interrupt save routine (SINTSI) that performs the following: 

@® Save R4 and R5 

@ Save the Kernel mapping (APR 5) 

® Load APR 5 to map the driver 

@® Transfer control to the driver via a JSR instruction 

@ Restore the mapping after return from the driver 

@ Perform interrupt exit processing 

@® Restore R4 and R5 

@® Return from interrupt 


Thus, the interrupt vector for a controller serviced by a driver 
points to an ICB rather than to the driver. 


INTERRUPT 
CONTROL 
BLOCK 
(ICB) 


CONTROLLER 
NUMBER 


INTERRUPT 
VECTOR 


DRIVER 


ZK-247-81 


Figure 1-2: Interrupt Dispatching for a Driver 


The ICB conceptually allows up to 128 controllers of the same type on 
a system. The low-order four bits in the PS of the interrupt vector 
restricts the number of controllers to 16. In the ICB, the system 
maintains a controller group number and the PS bits describe the 
controller number within the group. To obtain the controller index 
(controller number #2), the executive interrupt service routine first 
multiplies the controller within group number that was in the low 4 
bits of the PS by two. The group number byte in the ICB is then added 
to this number. | 
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The simplest case in handling an interrupt is that in which a 
controller can have only one unit active at any one time. Multiple 
controllers may be active concurrently, yet only one unit per 
controller may be active. The interrupt service routine in the driver 
uses the controller index passed in R4 to index a table in the CTB and 
to access the proper KRB. From the KRB, the UCB (via K.OWN) may be 
determined to access the proper unit data and context. For those 
devices that have a static one-to-one static relationship between a 
controller and a perticular UCB, the controller index may be used to 
index a table of UCB addresses within the driver. 


The more complex case in dispatching an interrupt is that in which a 
controller can have multiple units operating in parallel. This is an 


advanced driver feature called overlapped seek I/O and is described in 
Section 1.4.1. 


1.3.3 Interrupt Servicing and Fork Process 


A driver handling an interrupt and operating at the partially 
interruptable level may need to (1) access structures in its data base 
or (2) call centralized Executive service routines which may access 
structures in the data base. Because a driver may have more than one 
process active simultaneously, the driver itself may need to access 
structures in the data base shared among separate, unrelated 
processes. A method must exist to coordinate access to the data 
structures shared among the processes and the Executive. 


The mechanism that coordinates access to the shared structures is 
called the fork process. An Executive routine, called fork (SFORK), 
causes the driver process to be placed in a queue of processes waiting 
for access to the shared data structures, to run at processor priority 
level 0, and to be completely interruptable.* A driver must’ therefore 
call the fork routine before it calls any other Executive service 
routine (except for SINTSI), or before it accesses any device-specific 
(nonprivate) structures in its data base. If a driver does not follow 
this protocol, it will corrupt the system data base and lead to a 
system crash. 


A driver that calls the fork routine requests the Executive to 
transform it into a fork process. The routine saves a snapshot of the 
process in a fork block. The snapshot is the context of the driver 


* By convention, drivers may operate at a partially interruptable 
level for no more than 500 microseconds. Some drivers conceivably 
could need more time than this convention allows. Thus, an additional 
reason for the fork mechanism is to preserve the response time of the 
system and not lock out interrupts from lower-priority levels. 
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process--the PC of the process and the contents of R4 and R5. The 
fork block itself can (and usually does) reside in the I/O data 
structure holding the status information of the device being serviced 
(that is, the status control block, or SCB). The Executive maintains 
a list of fork blocks in FIFO order. A new fork block is added to the 
list after the last block in the list. 


When the driver calls SFORK, the CPU priority is lowered to 0, which 
allows other interrupts to be serviced. When there are no more 
pending interrupts (they have either been dismissed or the drivers 
have called SFORK), the Executive checks to see whether the first 
interrupt preempted a priority O Executive process. If a preemption 
occurred, the Executive process is continued from where it was 
interrupted.* If no _ priority level 0 Executive process was 
interrupted, the Executive executes the process at the head of the 
fork list. The Executive restores the saved context of the process 
from the SCB and returns control to the driver at the statement 
immediately following the call to the fork routine. The process is 
unaware that a pause of indeterminate length has elapsed. 


Fork processes thereby are granted FIFO access to the common I/O data 


structures. Once granted such access, a fork process has control of 
the structures until it exits. The protocol guarantees that the 
driver process has unrestricted access to shared system data 


Structures. As one fork process exits, the next in the list is 
eligible to run and access the data structures. Thus, the fork 
mechanism allows both controlled access to the common data _ structures 
and sufficient time to process an interrupt without locking up the 
system. 7 


The status of a fork process lies between an interrupting routine and 
a task requesting system resources. This is known as "system state." 
Interrupt routines are run first and can be interrupted only by 
higher-priority interrupts. Processes in the fork list run after 
other system processes either terminate or call SFORK themselves. 
Because system processes save and restore user task registers and 
cannot be interrupted by a fork process, a fork process can use all 
registers. The fork processes are completely interruptable. Tasks 
run only when the fork list is empty. 


The fork mechanism establishes linear, or serial, access to the shared 
data structures. For example, an Executive routine that completes I/O 
processing (S$IODON) manipulates the I/O queue to deallocate an I/O 
packet that the driver processed. If multiple processes were allowed 
to alter the queue at random times, the queue pointers could become 


* The stack must be restored to its state on interrupt entry before 
calling SFORK. Therefore, it cannot be used to pass additional 
context. | 
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disarranged. Without the fork mechanism, any process could be 
interrupted by a higher-priority process and not be able to complete 
its manipulation. Because the Executive completes a currently active 
fork process before it starts the next fork process in the queue, the 
integrity of the I/O data structures is maintained if all routines 
that call SIODON run at system state. 


Between the time that a driver process calls SFORK and the Executive 
Starts the process at system state, the driver cannot call SFORK again 
for that same device. If the SFORK routine is called again before the 
first process starts, context stored in the fork block for the first 
fork process iS overwritten. However, once a fork process starts, the 
data in the fork block is stale and the process may call SFORK again 
while it is at system state. If the driver does not enSure against 
unexpected interrupts, it may double fork as described above. Asa 
result of the double fork, the system will bugcheck (crash) with an 
IOT trap as a result of a failed sanity check while queuing the 
forkblock. A common protocol used by DIGITAL device drivers is to 
clear the saved PC in the forkblock immediately following a fork, and 
to test this work before forking. If the word is non-zero, it is not 
possible to call SFORK. 


If all drivers adhere to the interrupt protocol, the integrity of the 
I/O data structures is preserved. Thus, when a device interrupt 
occurs while a fork process is executing, the protocol demands’ that 
the service routine handling the interrupt not destroy any of the 
registers. The registers are part of the context of the fork process. 
After the driver dismisses the interrupt or itself becomes a fork 
process, the interrupted fork process can safely resume execution with 
its proper context. If any driver violates the protocol, the 
integrity of the I/O data structures is endangered. (That is, the 
system crashes in mysterious ways.) 


1.3.4 Nonsense Interrupt Entry Points 


All vectors for off-line devices and vectors for which there are no 
devices contain the addresses of Executive nonsense interrupt entry 
points. Code at these special entry points exists to properly dismiss 
unexpected interrupts from these devices via an RT1l instruction. 


1.4 ADVANCED DRIVER FEATURES 


This section introduces optional features so you can better understand 
the structures and concepts described in the remainder of the manual. 
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1.4.1 Overlapped Seek I/O 


Some disk devices allow multiple device units attached to the same 
controller to execute operations in parallel. This is called 
overlapped seek Support and is a software option designed to take 
advantage of a hardware feature found in most advanced disk drives and 
controllers. This feature allows any or all drives to be attached to 
the same controller, allowing this functionality to execute a seek 
function simultaneously. Each unit may perform a seek operation 
independent of what another unit may be doing. Only one data transfer 
can occur at any one time. Some types of drives allow seek functions 
to overlap a data transfer function, whereas other types do not. 


The increased difficulty for overlapped seek devices stems from 
determining whether the controller or the unit generated the. 
interrrupt. Most control functions issued to the drive unit 
(including the positioning commands SEEK and SEARCH) terminate with a 
unit interrupt. The controller reports the physical unit number of 
the interrupting unit. A controller interrupt indicates’ the 
termination of a function (usually a data transfer command) that 
changes the controller status from busy to ready. Only one unit may 
issue a data transfer complete notification to a particular controller 
at any one time because only one data transfer can be in progress at 
any one time. Most hardware defers seek termination interrupts until 
the current data transfer is complete. | 


To handle interrupts for a device that supports overlapped _ seek 
operations, a device controller-specific interrupt service routine 
must be built into the driver to examine the device registers in order 
to determine whether the interrupt was initiated by the controller or 
the drive unit. Using the controller index on interrupt entry, the 
routine uses this as an offset into a table of addresses ina 
structure (called the controller table or CTB) in the I/O data base. 
The routine accesses the table to determine the address of the I/O 
data structure of the interrupt controller (called the controller 
request block or KRB) that generated the interrupt. Accessing the KRB 
yields the address of the CSR of that controller and having the CSR 
address allows the routine to examine the device registers. 


If the controller itself initiated the interrupt, the routine 
determines the data base structure of the unit that is active. This 
determination is possible because such a controller interrupt relates 
to a termination of a data transfer, and only one such unit can be 
active for a data transfer. A cell in the KRB has the address of the 
data structure describing the active unit (the unit control block or 
UCB). The routine can then determine the address of the driver 
dispatch table and transfer control to the driver. 
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If a device unit initiated: the interrupt, the routine retrieves its 
unit number from the device registers. Using the physical unit 
number, the routine indexes a table at the end of the KRB to yield the 


address of the related UCB. The driver is entered through the driver 
dispatch table. 


1.4.2 Delayed Controller Access 


Drivers that support overlapped seeks also must request access to a 
controller before executing a function on an independent unit and must 
release access after completing the function. To take maximum 
advantage of simultaneous operation of units on one controller, the 
system delays controller access when the controller is busy. 


The Executive maintains a request queue for the controller. Whenever 
a driver process requests access to a controller and must wait for 
access to the controller, the Executive places the associated fork 
block in the controller request queue. When a driver releases a 
controller, the Executive automatically grants access to the next 
driver process waiting for access. Precedence is given to positioning 
requests over requests for data transfer. The controller request 


queue thereby provides the means’ for the Executive to synchronize 
access. | 


1.4.3 Full Duplex Input/Output 


In certain circumstances it may be necessary for a driver to. handle 
more than one I/O request on a unit at the same time. Typically a 
driver processes only one I/O packet per unit at any one time. In 
normal operation the driver calls the Executive routine $S$GTPKT to get 
an I/O packet to process. When SGTPKT returns an I/O packet, it marks 
the device busy and does not allow additional I/O until the first I/O 
activity completes. Therefore, only one I/O process can be in 
progress at the same time on a device. Full duplex operation allows 
more than one I/O process to be in progress on a device at the same 
time. 


To allow full duplex operation, the $GTPKT routine has a special entry 
point called $GSPKT. A driver calling $GSPKT specifies an acceptance 
routine, to which $GSPKT returns control when an eligible packet is 
found. The acceptance routine determines whether to accept or reject 
the packet. The criteria that the acceptance routine applies could be 
that a write request is accepted if a write has just completed or that 
a read request is accepted if a read has just completed. Lt. the 
routine rejects the packet, it indicates so to $GSPKT, which continues 
to search for another packet. If the acceptance routine accepts the 
packet, $GSPKT dequeues the packet and passes it to the driver but 
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does not modify U.BUF and U.CNT in the unit control block (UCB) nor 


does it mark the device busy. As a result, during full duplex 
operation the device appears idle even while it is processing an I/O 
request. For this reason, it may be difficult to make use of the 


executive's standard driver timeout facility. Clock queue entries are 
suggested. 


To complete an I/O request under full duplex operation, the driver 
calls the SIOFIN routine rather than the SIOALT or SIODON routine. 
SIOFIN does final processing without making the device look idle, as 
SIOALT and S$IODON attempt to do. In full duplex operation, a unit 
will always appear idle to the system and the driver acceptance 
routine will determine whether the device can handle an I/O request. 


A driver handling full duplex operations requires augmented data base 
structures. The conventional data base structures are defined for 
only one I/O request in progress per unit. Because the driver has to 
keep more information concerning a unit that allows two I/O requests 
in progress, you may have to alter the UCB and other data base 
structures to provide additional offsets. The DIGITAL-Supplied full 
duplex terminal driver not only uses a lengthened UCB and a 
nonstandard SCB, but also connects to a dynamically allocated UCB 
extension. 


1.4.4 Buffered Input and Output 


Typically, data for input and output requests are transferred directly 
to and from task memory. To allow the successful transfer of data, 


the task cannot be checkpointed until the transfer 1s complete. For 
most high-speed devices, the transfer occurs quickly enough so that a 
task does not occupy memory for too long ae time. For slow-speed 


devices, however, some mechanism must be available to avoid binding 
memory to a task for too long a time while the task is performing I/O. 


Using the routines STSTBF, SINIBF, and SQUEBF in the Executive module 
IOSUB, a driver can execute an I/O request for a slow-speed device and 
allow the task to be checkpointed while the request is in progress. 
To perform the I/O request, the driver buffers the data in memory 
allocated to the driver while the task is checkpointed and the I/0 
request iS in progress. 


To test whether a task is in a proper state to initiate I/O buffering, 
the driver calls the STSTBF routine and passes it the address of the 
I/O packet. By extracting the address of the task control block (TCB) 
from the I/O packet, STSTBF can examine various task attributes. For 
example, if the task is not checkpointable, buffered I/O is not 
desirable. STSTBF returns to the driver and indicates whether 
buffered I/O can be performed. 
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If buffered I/O can be performed, the driver performs two operations. 
First, it establishes the buffering conditions. For an output 
request, it copies the task buffers to dynamically allocated pool 
space. For an input request, it allocates sufficient pool space to 
receive the incoming data. Second, the driver calls the SINIBF 
routine to initiate the I/O buffering. SINIBF decrements the task I/O 
count, increments the task's buffered I/O count in T.TIO, and releases 
the task for checkpointing and shuffling. If the task is currently 
blocked, the task state is transformed into a "stopfor" state until 
the task is unblocked, buffered I/O completes, or both. Checkpointing 
the task is subject to the normal requirements of an active or 
“stopfor" state as described in the P/OS Reference Manual. 


After the driver transfers the data, it calls the SQUEBF routine to 
queue the buffered I/0 for completion. SQUEBF sets up a kernel 
asynchronous system trap (AST) for the buffered I/O request and if 
necessary, unstops the task. When the task is active again, a routine 
(SFINBF) in the Executive module SYSXT notices the outstanding AST and 
processes it. (If the request is for input, the routine copies the 
buffered data to task memory.) This mechanism occurs transparently to 
the task, thus the name kernel AST. The routine then calls the driver 
to deallocate the buffer from pool. SIOFIN completes the processing. 


1.5 OVERVIEW OF INCORPORATING A USER-WRITTEN DRIVER INTO P/OS 


A callable system service called PROLOD is responsible for loading a 
driver into memory. PROLOD establishes the linkage between the data 
base structures in the system device tables and the driver code being 
loaded. Another callable system service called PROUNL can remove a 
driver from memory. (Although PROLOD removes a driver, it does not 
remove a data base.) 


To incorporate a user-written driver into P/OS, you first create two 
modules, one in which you define the data base and the other in which 
you include the driver code itself. You must supply in your _ code 
symbols and labels that PROLOD needs. 


PROLOD also loads the driver's data base. It reads the driver symbol 
definition file to find the start and end of the data base in the 
driver image. (Thus, you must have defined its start and end in _ the 
data base source code.) Knowing the start and end, PROLOD reads the 
Gata base from the driver image. It then places the data base in the 
system pool so that it resides in Executive address space, accordingly 
relocates pointers and links within the data base to be valid 
Executive addresses, and also connects the CTB and DCB(s) in the data 
base to the system device tables. Moreover, so that the system device 
tables are not corrupted by an incorrect data base, PROLOD performs 
many consistency and validity checks on the data base being loaded. 
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You must build (1) a single image containing the driver code module 
followed by the driver data base module and (2) a symbol definition 
file on which PROLOD depends to find critical data base and driver 
locations. You will link the driver image to the Executive version 
under which the driver will run. However, the driver image will be 
separate from the Executive image. PROLOD is responsible for loading 
both your driver data base and driver code, for connecting the data 
base to the system device tables, and for connecting your driver code 
to the data base. 


CHAPTER 2 


DEVICE DRIVER I/O STRUCTURES 


This chapter deals mainly with structures at the block level, their 
relationship to the hardware configuration and functionality 
Supported, and their relationships to each other. The precise 
description of each structure is given in Chapter 4. 


2.1 I/O STRUCTURES 


The main elements in the driver I/O environment essentially define the 
logical and physical characteristics of the supported hardware and 
establish the links and connections by which routines can access_~ and 
manipulate driver data. The following subsections describe the 
control blocks that a driver data base module defines, and explain in 
general terms the purposes for each block. 


2.1.1 Controller Table (CTB)* 


A controller table defines a unique controller type on the system. A 
CTB must exist for each physical controller type. All controller 
tables are linked together, ina list, with the head of the list 
SCTLST in the Executive common = area. The list of the controller 
tables is one of the threads through the system data base to _ provide 
access to all device-related data. The link in the last CTB in the 
list has a value of zero. 


Associated with each CTB is a 2-character ASCII controller name which 
must be unique within the driver. This unique name allows PROLOD to 
find the correct CTB for the controller type. 


Drivers which are not associated with hardware devices (such as _ in 
memory disk or pipe driver) do not need a CTB or KRB. DCBs, SCBs, and 
UCBs are a sufficient database. 
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Any user-written driver data base must have its own CTB. The 
user-created controller table will also be linked into the system CTB 
list, if necessary. 


A CTB has generic status information, links, and pointers to other 
structures on the system. The table of KRB addresses in the CTB is 
the means by which the Executive handles interrupts for the controller 
type and dispatches to the correct driver routine. 


2.1.2 Controller Request Block (KRB)* 


The controller request block is the means by which the Executive 
maintains controller-specific or hardware-specific information and 
accesses the correct information for a unit which its associated 
controller owns. One KRB exists for each device controller of a given 
type in the configuration. It stores such data as the the device CSR 
and vector addresses, the slot number, the interrupt controller CSR 
address, and controller's status. 


In a configuration where a device controller allows only one operation 
at a time, the KRB is combined with another structure called the 
Status control block (SCB). (The SCB holds context for a unit while 
an operation is in progress.) Because only one access path is possible 
in such a configuration, unit context is always associated with the 
same controller. Moreover, because only one operation is possible at 
a time, the same context storage area can be used for all units 
attached to the controller. Thus, in a conventional driver operating 
environment, the context storage is merely an extension of the 
controller request block. | 


In a configuration where multiple operations in parallel on the _- same 
controller are possible, the controller context is separate from each 
independent unit context. Therefore, each unit capable of operating 
independently on a controller has the context of the current I/O 
operation stored in an SCB separate from the controller KRB. In_ such 
an operating environment, any unit can access the controller while 
Other operations are pending, but only one unit can have access at a 
time. The KRB indicates which unit owns’ the controller for the 
Current operation, and synchronizes access among driver processes on 
the same controller. 


Where multiple operations in parallel are allowed on a controller, it 
may be necessary to delay access to the controller when it is busy. 
Therefore, in the KRB the Executive holds the head of a list of access 
requests called the controller request queue. The list contains fork 


See footnote on page 2-1. 
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blocks for driver processes awaiting controller access. The queue is 
the means by which the Executive serializes access to the controller. 


When a controller allows parallel operations, the software must have a 
means of determining which of several units generated an interrupt. 
The KRB, therefore, contains a table of addresses which associate the 
controller with all the units connected to it. This table, indexed by 
physical unit number, must appear if the controller in question 
Supports overlapped seek operations or multiple simultaneous data 
transfers for each physical unit attached to the controller (comm. 
Multiplexers). 


The KRB also holds the configuration status of the controller. If the 
KRB indicates that the controller is off-line, no activity can take 
place on any unit connected to the controller. 


2.1.3 Device Control Block (DCB) 


The device control block describes the static characteristics of a 
device type and of units associated with a certain device type. The 
DCB is the means of access to the driver dispatch table and thus’ to 
the driver. At least one DCB exists for each logical type of device 
on a system. There may be more than one DCB for a logical device 
type. (Note that the logical device type is not the same as the 
physical device type.) 


A cell in each device control block forms a link in a forward-linked 
list, with the head of the list starting in a cell ($SDEVHD) in the 
Executive common area. This list, as with the CTB list, is a main 
thread through the system data structures to device-related data. The 
link in the last DCB in the list has a value of zero. 


The static data in the DCB gives such information as the generic 
device name, unit quantity and links to individual unit data, the 
address of the driver dispatch table, and types of I/0 functions 
Supported by the driver. Typically, the Executive QIO directive 
processing code and not the driver code accesses the DCB. 


2.1.4 Unit Control Block (UCB) 


The unit control block holds much of the static information about an 
individual device unit and contains a few dynamic parameters. 
Although unit control blocks need not be any prescribed length for 
different devices, all unit control blocks for the same DCB must be of 
equal length. (The UCB length is stored in the device control block 
to calculate the offset to a particular UCB in the concatenated set of 
UCBs described by the DCB's logical unit numbers.) This condition 
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allows the UCB to contain varying amounts of unit- and 
device-independent data for different types of devices. 


A UCB, one of which exists for each device unit, enables a driver to 
access most of the other structures in the I/O environment. A UCB 
provides access to most of the dynamic data associated with I/O 
operations. Given the address of a UCB, a driver may readily find 
most of the other data structures in which it is interested because 
the proper links exist. Because of this access information, the UCB 
is a key control block in the driver I/O structure. 


The static data in the UCB includes pointers to other I/O structures, 
definitions of unit control bits which regulate directive processing, 
definitions of unit status bits which describe operational conditions, 
and definitions of unit- and device-dependent characteristics and 
storage cells. : 


Data in the UCB is accessed and modified by both the Executive and the 
driver. 


2.1.5 Status Control Block (SCB) 


The status control block holds driver context for operations on a 
device unit. In the SCB are stored such data as the pointer to the 
head of the queue of input/output requests; the link to the fork 
blocks queued for the unit; the fork process context; timeout, and 
unit status; and the address for the controller request block (KRB) 
representing the device controller (if the device has a controller). 


The Executive accesses the SCB to set up an I/O request, to store 
context while a request iS in progress, and to post results and 
status. When the driver accesses the SCB, it is usually for read 
access only. 


The number of status control blocks depends on the processing Support 
in the Executive. If the controller itself cannot handle parallel 
operations, only one SCB is needed for each controller. In such a 
case, a controller can have only one unit processing a command at one 
time, and there is no need to store context for more than one unit at 
a time. There is also no need for a physically separate controller 
request block (KRB) to separate generic data from unit context. 
Therefore, the driver data base contains the required KRB cells in the 
status control block since the KRB and SCB overlap. 


If the controller allows parallel operations and the Executive 
Supports this feature, there must be one SCB to store context for each 
unit capable of operating independently on the controller. In such a 
configuration, a cell in each SCB points to the KRB of the controller 
to which the units are connected. Should the controller allow 
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parallel data transfers to individual units independently and the 
driver uses SGSPKT and SIOFIN, the driver could store unit context in 
a UCB extension and reduce the number of SCBsS required. 


2.2 DRIVER DISPATCH TABLE (DDT) 


The driver dispatch table* contains the entry points to and the 


interrupt entry addresses for the driver. An entry point is the 
location at which the Executive calls the driver to perform a specific 
function. An interrupt entry address is a location to which the 


central processor or the Executive transfers control within the driver 
for servicing hardware interrupts. The pointer to the interrupt entry 
address resides in an interrupt control block. 
Every driver has four conventional entry points as follows: 

e 1/0 initiation 

@® cancel I/0 

@® device timeout 


@® device powerfail 


Two more entry points are added for controller and unit on-line. and 
off-line status changes: 


@® KRB status change 
@ UCB status change 


For many devices, these status change entry points are merely a return 
to the Executive calling routine. 


There are two additional entry points that have been added for_ the 
advance driver feature of buffered I/O and terminal driver processing: 


@® Deallocate buffers (buffered I/O) 


@e Send next command (FDX TTDRV) 


* The DDT is not a structure in the strict sense of the word because 
it is defined in the instruction part of the driver code. However, 
because it contains addresses for dispatching code, it is included in 
the data structure description. 


DRIVER DISPATCH TABLE (DDT) 


2.2.1 I/O Initiation 


The Executive transfers control to this entry point to inform. the 
driver that work for it is waiting to be done. To reduce work for the 
driver, the Executive performs predriver-initiation processing. 
(Predriver initiation is described in Chapter 3). If, at the end of 
predriver processing, the Executive has I/O packets queued for the 
driver, it calls the driver at this entry point. 


When the driver gets control at its I/O initiation entry point, R5 
contains the address of the UCB for the unit on which the request is 
to be processed. To establish access to the I/O packet, the driver 
calls an Executive routine that either returns information in 
registers concerning both the packet to be processed and the 
associated data in order to gain access to the data structures* or 
causes the driver to dismiss itself. (There may be no packet to 
process or the driver may already be busy.) 


Once control is returned to a driver and there is a request to 
process, the driver must extract the information from the registers, 
establish data within the control blocks, and process the request. 
This means that the driver proceeds with an I/O request until it 
issues a command to the controller hardware, which physically 
initiates the I/O operation. 


Typically a driver is called at this entry point after an I/O packet 
has been inserted into the I/O queue. However, a driver can be called 
before a packet is placed in the I/O queue. Refer to the description 
of the U.CTL control flag UC.QUE in Section 4.4.4 for information on 
queueing an I/O packet to the driver. 


2.2.2 Cancel I/O 


To terminate an in-progress I/O operation, the system flushes the I/O 
queue and calls the driver at this entry. There are many Situations 
in which a task must terminate I/O. When such a termination becomes 
necessary, a task issues an Executive QIO request and the Executive 
relays the request to the driver by calling it at this entry point. 


The driver is responsible for checking that the I/O operation 
in-progress was issued from the task that is forcing the termination, 
and for completing or terminating the operation before returning to 
the caller. 


* The SGTPKT routine, which gets a packet for the driver to process, 
1s described in Chapter 7. 
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Typically, a driver is called at this entry point only when an I/O 
Operation iS in progress. A driver also can be called, even if the 
unit specified is not busy. Refer to the description of the U.CTL 
control flag UC.KIL in Section 4.4.4 for information on unconditional 
cancelling of I/O. (For instance, the driver may need to clean up 
data structures created during pre-initiation processing (UC.QUE=1) 
and has "hidden" the I/O packet listhead in some other structure). 


2-2-3 Device Timeout 


When a driver initiates an I/O operation, it can establish a timeout 
count. If the operation fails to complete within the specified 
interval, the Executive notes the lapse and calls the driver at this 
entry point. Using this facility, a driver can wait for an interrupt 
but need not hang if the interrupt never occurs. Thus, no driver 


should ever stall on a request because a hardware failure prevented an 
expected interrupt from happening. 


NOTE 


Extreme caution must be exercised to avoid completing 
an I/O request twice. It can happen once for timeout, 
and again when a pending forked process becomes active 
and completes I/O again. 


2.2.4 Device Power Failure 


The Executive calls the power failure entry point upon_ successful 
completion of loading. 


2.2.5 Controller and Unit Status Change 


Two entry points are required for configuration status changes of the 
controller and units. The Executive enters one entry point to put the 
controller on-line and take it off-line. The other entry point, 
called once for each unit whose status changes, is for putting units 
on-line and taking them off-line. The driver must show’ successful 
completion of the on-line or off-line request or the Executive will 
not effect the status change. 


DRIVER DISPATCH TABLE (DDT) 


2.2.6 Device Interrupt Addresses 


Control passes to an interrupt address when a device, previously 
initiated by the driver, completes an I/O operation and causes an 
interrupt in the central processor. A device may have associated with 
it more than one interrupt entry. For example, a full duplex device 
such as a terminal will have two interrupt addresses. 


The interrupt addresses are arranged in a block in the DDT. The 
arrangement is general enough to support multicontroller drivers such 
as the terminal driver. The block defines the address or addresses to 
include in the vector for the driver. 


2.3 TYPICAL CONTROL RELATIONSHIPS 


This section presents different arrangements of the control structures 
that are found in P/OS. The section concentrates on the relationships 
among device control, unit control, status control, and _ controller 
request blocks and controller tables based on hardware and functions 
Supported. Descriptions of the detailed contents of the structures is 
left to Chapter 4, where the coding requirements are presented. Some 
of the arrangements are not conventional but are shown to convey’ the 
flexibility. Section 2.4 shows how such arrangements fit into the 
overall system I/O data structure. 


The arrangements described in this section illustrate the strategy in 
offering a flexible I/O data _ structure. There need be only one 
controller table for each controller type. Multiple-device control 
blocks for a single device type reflect the capability to handle 
varying characteristics. The existence of one or more status control 
blocks depends on the degree of parallelism possible: one SCB for 
each controller servicing several units (no parallelism); or one _ for 
each device unit combination on the same controller (unit operation in 
parallel). 


The I/O data structure reflects the hardware configuration that the 
data structures describe. The flexibility in the data structure 
arrangements provide flexibility in configuring I/O devices. The 
information density in the structures themselves reduces the coding 
requirements for the associated drivers. 


2-3-1 Multiple Units per Controller, Serial Unit Operation 


A typical arrangement of structures for a user-written driver is shown 
in Figure 2-l. The arrangement could represent an RX50 controller 
with dual drives. A single controller table (CTB) defines’ the 
existence of the controller type on the system. One device' control 
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block (DCB) establishes the characteristics for the type of device 
running on the controller. 


DCB CTB 
List | List 


ZK-249-81 


Figure 2-1: Multiple Units per Controller, Serial Unit Operation 


The status control block (SCB) and controller request block (KRB) are 
contiguous in this arrangement because the software does not allow 
another I/O operation to begin while the controller is busy. A 
separate unit control block (UCB) describes each unit attached to the 
controller. The UCBs are associated with the SCB, which contains’ the 
context of the operation currently in progress. 


2.3.2 Multiple Controllers, Single Unit per Controller 
Another typical conventional arrangement of structures for a 


user-written driver is shown in Figure 2-2, which could represent two 
Winchester controllers, one with an RD50 and the other with an RDdl 
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attached. It represents the simplest case of driver processing. 
Figure 2-1 shows what is required for a controller that allows only a 
single I/O operation for each controller. A single controller table 
defines the existence of the controller type on the- system. One 
device control block establishes the characteristics for the type of 
device running on the controller. 


The status control and controller request blocks are contiguous’ in 
this arrangement because, while the controller is busy, another I/0 
operation cannot begin. Only one SCB iS necessary to store the 
context of the unit operation. The UCB points to the SCB, which in 
turn points to the KRB of the unit's controller. Because the system 
must handle interrupts from multiple controllers, the controller table 
points to the KRB of each controller present. 


DCB CTB 
List List 
DCB CTB 
KRB 
UCB SCB 
B 
ve KRB 
SCB 
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Figure 2-2: Multiple Controllers, Single Unit per Controller 
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2.3.3 Parallel Unit Operation 


Some devices, such as the <this space for rent>, allow multiple units 
to have seek operations in progress at the same time. In particular, 
this controller would allow such operations to overlap a data 
operation. Figure 2-3 shows the arrangement needed in the software 
structures to support parallel operations on one controller. 


Two additional structural changes are required from the serial 
Operation arrangement. First, because more than one unit may have an 
operation pending at the same time, a structure is needed to_ store 
unit context. Therefore, for each unit (and each unit control block) 
there is a separate. status control block. Second, because interrupts 
can come from more than one unit, some way must exist to access the 
proper unit. As a result, the controller request block contains a 
table of unit control block addresses that allows the driver to find 
the structures for the unit generating an interrupt. 


DCB CTB 


KRB 
UCB 
Table 


Figure 2-3: Parallel Unit Operation (Overlapped Seek) 


ZK-251-81 


2.4 OVERVIEW OF DATA STRUCTURE RELATIONSHIPS 


This section presents an overview of the relationships among the 
user-written driver data structures previously introduced in this 
chapter and the Executive I/O structures and DIGITAL-supplied driver 
structures. The goal of the section is to convey the general manner 
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in which user-written structures and code link into the system I/O 
scheme and to describe generally the use to which the system puts the 
structures. The specific user-written structures are simplified 
somewhat so that the emphasis is placed on the linkages with other 
parts of the system rather than on the details of user-written 
structural relationships. 


This section should be used with Section 2.3 to understand the general 
structural concepts. For example, Section 2.3 describes various 
arrangements of unit control, status control, and controller request 
blocks based on hardware functions the software structures Support. 
This section treats such arrangements as an engineering black box that 
is oriented in the general I/O environment. Thus, in the generalized 
I/O data structure depicted in this section, the pointers in the KRB 
table of the SCB are not shown and the table is simply marked KRB 
Table. 


Figure 2-4, which provides the basis for the presentation of the I/0 
data structure, shows the individual elements and the important link 
fields within them. The numbers in the figure correspond to _ the 
numbers in the lead paragraphs of the text to simplify the discussion 
and to guide you through the data structures. 


1. The location represented by the Executive symbol SDEVHD is a 
cell in system common (SYSCM). It is the head (or start) of 
a singly-linked, unidirectional list of all device control 
blocks in the system. The first word in each DCB is a link 
to the next DCB. 


The list of device control blocks is one of the two threads 
through the system data tables for device-related 
information. For example, the list is the means’ by which 
executive routines scan the data structures to determine what 
devices are on the system and what is the status of units. 
User-written device control blocks must be linked into the 
list of system defined DCBs. 


2. Every driver is associated with a partition control block 
(PCB). The PCB defines the characteristics of the memory 
area into which the driver is’ loaded. The Executive and 
services such as PROLOD reference the data in the PCB. A 
driver is not concerned with the PCB. 


3. If a task is attached to a unit, the UCB has a pointer to the 
task control block (TCB) of that task. 
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The task header is an independent entity in the I/O data 
structure and the driver never accesses it. (In fact, it may 
not be memory resident.) The task header may be in the 
primary pool, or in physical memory immediately before the 
task region when the task's "task region" is resident in 
memory in both cases. 


A logical unit table (LUT) entry in the task header has_ two 
items of interest: a pointer to an associated unit control 
block and, if a file is being accessed, a pointer to a window 
block. The Executive accesses the logical unit table of a 
task during a QIO request and indexes the table by the 
logical unit number specified in the QIO request. 


A device control block haS a pointer to the unit control 
block of the first related unit. Because the length of a UCB 
is stored in the DCB and all UCBs are allocated in a 
contiguous area, access to all the UCBs related to that DCB 
is possible. This arrangement allows software to access all 
related unit information for a device type. 


A DCB also has a pointer to the start of the driver dispatch 
table. This pointer ailows the Executive to call the driver 
at its entry points to process an I/O-related request. 


Fach unit control block contains a pointer back to its 
related DCB. This backpointer allows the Executive interrupt 
dispatch code to enter the proper driver (through the pointer 
to the driver dispatch table). 


Associated with each UCB is a status control block. The SCB 
is shared by all units for a device type that does not 
require units to operate in parallel. When units can operate 
in parallel, each UCB has its own associated SCB. 


As part of processing a QIO directive (queued I/O request), 
the Executive builds a structure called an I/O packet. 
Storage for packets is in the system dynamic storage region 
(the primary pool). The Executive connects the packets by a 
pointer in each packet to form a linked list called the I/O 
queue. The Executive maintains two pointers in the SCB to 
the list of packets. The first pointer is to the start of 
the list and the second pointer is to the last packet in the 
List. 


Normally, the driver should not access the list of I/0 
packets directly. When the Executive transfers control to 
the driver to initiate processing of an I/O request, the 
driver immediately calls an Executive service routine to get 
a packet to process. The routine passes, to the driver, data 
sufficient to process the request (for example, the address 


2-14 


OVERVIEW OF DATA STRUCTURE RELATIONSHIPS 


of the packet). Thus, the Executive, and not the driver, 
removes a packet from the queue of packets. However, in 
performing the I/O request, the driver can access’ certain 
fields in the packet to be processed because a pointer to the 
currently active I/O packet is kept in the SCB.* 


The Executive determines the ordering of packets in the 


queue. Typically, higher-priority requests are placed at the 
head of the queue. 


8. At least one status control block (SCB) exists for each 
controller. Where a controller and software support 
operations in parallel on multiple units, one SCB exists’ for 
each unit capable of operating independently. A pointer in 
the SCB connects to the controller request block (KRB) of the 
controller to which the related unit is connected. 


The fork block in the SCB contains some of the driver process. 
context. The driver executes an Executive routine so that 
processing will occur at fork level. To preserve processing 
Status, the routine stores some context in the fork block. 
When the driver eventually runs again, the fork processing 
restores the proper context from the fork block. 


The fork blocks for pending driver processes are connected in 
a Singly-linked list, the head of which is in a location 
(SFRKHD) in the Executive’ region. Generally, the fork 
processing routines link a fork block in FIFO order. At 
location $FRKHD+2 the executive maintains a pointer to the 
last fork block in the list. 


9. Associated with each open file on a mounted volume is a_ file 
control block (FCB). The file system alone uses the FCB to 
control access to the file. 


10. For each open file on a mounted volume, a window block exists 
for each task that has the file open to hold pointers to 
areas on the volume on which the file resides. The function 
of the window block is to speed up the process of retrieving 
data items from the file. (The associated ACP need not _ be 
called to convert a virtual block number ina file toa 
logical block number on the device.) The driver is_ not 


* Normally, the driver does not directly manipulate the T/O queue. An 
exception is when a driver needs to examine an I/O packet before it is 
queued or instead of having it queued. This exception involves a 
Status bit in a control byte of the unit control block. For more 
information on queuing of I/O packets to the driver, refer to the 
description of the UC.QUE bit in Section 4.4.4. 
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concerned with the window block or this VBN to_ LBN 
conversion. 


The driver dispatch table (DDT) is part of the driver code 
and is the means by which the executive calls the driver. 


The controller request blocks (KRB) are linked into the I/O 
data structure through the pointers in the controller table 
(CTB). 


The KRB table in the CTB allows the Executive access to the 
structures for a controller when it initiates an interrupt. 
To report the termination of a data transfer command, a 
controller initiates an interrupt. (While such a 
controller-initiated interrupt is in progress, the hardware 
delays interrupts from units.) The driver determines the 
correct KRB by indexing the CTB with the controller index. 


For a controller that allows unit operation in parallel 
(overlapped seek support), the related KRB must have a table 
of UCB addresses. This table allows the driver to access the 
structures of the unit that generates an interrupt. When a 
unit interrupts, its controller has the physical number of 
the interrupting unit. The driver must retrieve the number 
and use it to index the UCB table in the KRB to access’ the 
proper unit control block. (For example, see DZDRV.MAC 
interrupt "B", door open, processing.) 


To support multilple parallel unit operations, the KRB_ also 
contains a queue to regulate controller access. This queue, 
known as the controller request queve, is a list of fork 
blocks for driver processes that have requested and have been 
denied immediate access to the controller. Tf the driver 
requests access to a controller and the controller is busy, 
the Executive forces the driver to wait for access by placing 
the fork block in the queue of processes waiting for access. 
The Executive gives precedence to control access over 
requests for data transfer by placing positioning requests 
onto the front of the queue and adding data transfer requests 
to the end of the queue. When a unit is given access, the 
controller status is set to busy and unit UCB address is_~ set 
to connect the KRB to the owned UCB. 


To indicate what unit to process on a controller initiated 
interrupt, a cell in the KRB points to the unit control block 
(UCB) of the unit that currently owns the _ KRB (data 
transfer). 


io 
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The KRB controller request queue listhead consists of two 
words. The first word points to the fork block in the SCB of 
the next unit to get access. The second word points to the 
fork block in the SCB of the last unit to get access. If the 
first word is 0, then the second word points to the first and 
no unit is waiting for access to the controller. 


The location represented by the Executive symbol SCTLST is a 
cell in system common (SYSCM). It is the head (or start) of 
a Singly-linked, unidirectional list of all controller tables 
(CTBS) in the system. A word in each CTB is a link to the 
next CTB. The last CTB in the list contains a link word of 


The list of controller tables is one of the two threads 
through the system for device-related information. (The list 
of device control blocks is the other thread.) A user-written 
controller table will be linked into the list of 
system-defined CTBs. This list is the mechanism by which 


system routines access I/O data structures for hardware 
information. 


One volume control block (VCB) exists for each mounted volume 


in the system. The VCB maintains volume-dependent control 
information. 


Pointers within the VCB connect to the file control block 
(FCB) and window block (WB). The FCB and WB control access 
to the volume's index file, which is a file of file headers. 
All FCBs for a volume form a linked list starting from the 
index file FCB. These linkages aid in keeping file access 
time to aminimum. A conventional driver never accesses any 
of these structures. 


CHAPTER 3 


EXECUTIVE SERVICES AND DRIVER PROCESSING 


The Executive provides services related to I/O drivers. Some services 
are provided before a driver process is initiated and are therefore 
called predriver initiation services. The predriver initiation 
services are those performed by the Executive during its processing of 
a QIO directive; these services are not available as Executive calls. 


Predriver initiation processing extracts from the QIO directive all 
I/O support functions not directly related to the actual issuance of a 
function request to a device. If the outcome of predriver initiation 
processing does not result in the queuing of an I/O Packet to a 
driver, the driver is unaware that a QIO directive was issued. Many 
QIO directives do not result in the initiation of an I/O operation. 


Other services are available to the driver after it has been given 
control, either by the Executive or as the result of an interrupt. 
They are available as needed by means of Executive calls. 


An important concept used in this section and in Chapter 4 is_ the 
state of a process. In P/OS, a process can run in one of two states, 
user or system. Drivers operate entirely in the system state; the 
programming standards described in Chapter 4 apply to system-state 
processes. 


3.1 FLOW OF AN I/O REQUEST 


Following an I/O request through the system at the functional level 
(the level at which this chapter is directed) requires that limiting 
assumptions be made about the state of the system when a task issues a 
QIO directive. The following assumptions apply: 


@e The system is running and ready to accept an I/O request. 
All required data structures for supporting devices attached 
to the system are intact. 
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The only I/O request in the system is the sample request 
under discussion. 


The example progresses without encountering any errors that 
would prematurely terminate its data transfer; thus, no error 
paths are discussed. | 


The controller in question executes only a_ single operation 
at a time. 


Predriver Initiation Processing 


The I/O flow proceeds as described below: 


die 


Task issues OIO directive 


The user program first either statically (by OQIOWSC, OQIOWS, 
QIOSC, or QIOS) or dynamically (by QIOWSS or QIOSS) creates a 
directive parameter block (DPB) containing information about 
what I/O is to be performed on what device. Then, it issues 
the directive. 


All Executive directives are called by means of EMT 377. The 
EMT causes the processor to push the PS and PC on the stack 
and to pass control to the Executive's directive processor. 


QOIO Dispatching 


The Executive directive dispatcher DRDSP ascertains that the 
EMT 1s a QIO directive and calls the QIO directive processor 
DROIO. 


First-level validity checks 


The QIO directive processor validates the logical unit number 


(LUN) and the Unit Control Block (UCB) pointer. DROQIO checks 
whether the LUN supplied in the directive parameter block is 
a legal value. If it is not a legal value, the directive is 
rejected. If the LUN is legal, DROQIO checks whether a _ valid 
UCB pointer exists in the Logical Unit Table (LUT) for the 
specified LUN. This check ascertains whether the LUN is 
assigned. If the check fails, the directive is rejected. If 
both these checks are successful, DROIO then performs’ the 
redirect algorithm. 
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4. Redirect algorithm 


Because the UCB may have been dynamically redirected by a 
Redirect command, QIO directive processing traces’ the 
redirect linkage until the target UCB is found. The target 
UCB provides the links to most of the other structures of the 
device to which the I/O operation will be directed. 


5. Additional validity checks 


The event flag number (EFN) is validated, as well as_ the 
address of the I/O Status Block (IOSB). If either is 
illegal, the directive is rejected. Immediately following 
successful validation, DROIO resets the event flag and clears 
the I/O status block. 


6. Obtain storage for and create an I/O Packet 


The OIO directive processor now acquires a 20-word block of 
dynamic storage for use as an I/O Packet. It inserts into 
the packet the device-independent data items that are _ used 
subsequently by both the Executive and the driver in 
fulfilling the I/O request. Most items originate in the 
requesting task's Directive Parameter Block (DPB). 


At this point, DROIO sets the directive status to +1, which 
indicates directive acceptance. Note that a directive 
rejection is a return to the caller with the C bit set. In 
addition, a directive rejection is transparent to the driver. 


7. Validate the function requested 
If the function is legal, DROIO checks to see whether’ the 
unit is on-line. If the unit is off-line, the packet is 
rejected. The function is one of four possible types: 
Control 
No-op 
ACP 


Transfer 


With the exception of Attach/Detach, control functions are queued to 
the driver. If the bit UC.ATT is set, Attach/Detach will also be 
queued to the driver. If the requested function does not require a 
call to the driver, the Executive takes the appropriate action and 
calls the I/O Finish routine (SIOFIN). 
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No-op functions do not result in data transfers. The Executive 
performs them without calling the driver. No-ops return a status of 
IS.SUC in the I/O status block. 


ACP functions may require processing by the file system. More 
typically, the request is a read or write virtual function that is 
transformed into a read or write logical function without requiring 
file-system intervention. When transformed into ae read or write 
logical function, the function becomes a transfer function (by 
definition). 


Transfer functions are address checked and queued to the _ proper 
driver. This means that DROIO checks the address of the I/O buffer, 
the byte count, and the alignment requirement for the _ specified 
device. If any of these checks fails, DROIO calls the I/O Finish 
routine (SIOFIN), which returns an I/O error status and clears the I/O 
request from the system. If the checks succeed, DROQIO either places 
the I/O Packet in the driver request queue according to the priority 
of the requesting task or, if the UC.QUE bit is set, gives the packet 
directly to the driver. (See Section 4.4.5 for a description of the 
UC;OUE Dre.) 


3.1.2 Driver Processing 


1. Request work 


To obtain work, the driver calls Get Packet (SGTPKT). SGTPKT 
either provides work, if it exists, or informs the driver 
that no work is available or that the SCB is busy; if no work 
exists, the driver returns to its caller. If work is 
available, SGTPKT sets the device controller and unit to 
busy, dequeues an I/O request packet, and returns to the 
driver. 


2. Issue I/O 


From the available data structures, the driver initiates’ the 
required I/O operation and returns to its caller. A 
subsequent interrupt may inform the driver that the initiated 
function is complete, assuming the device is interrupt 
driven. 


3. Interrupt processing 
When a previously issued I/O operation interrupts, the 
interrupt causes the driver to be entered. The driver 


processes the interrupt according to the programming protocol 
described in Chapter 1. According to the protocol, the 
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driver may process the interrupt at priority 7, at the 
priority of the interrupting device, or at fork level. If 
the processing of the I/O request associated with the 
interrupt is still incomplete, the driver initiates further 
I/O on the device (Step 9). When the processing of an I/O 
request is complete, the driver calls SIODON. 


4. I/O Done processing 


SIODON removes the busy status from the device unit and 
controller, queues an AST if required, and determines whether 
a checkpoint request pending for the issuing task can now be 
effected. The IOSB and event flag, if specified, are 
updated, and SIODON returns to the driver. The driver 
branches to its initiator entry point and looks for more work 
(Step 8). This procedure is followed until the driver finds 
the queue empty, whereupon the driver returns to its caller 
and the driver process vanishes. 


Eventually, the processor is granted to another ready-to-run 
task that issues a OIO directive, starting the I/O flow anew. 


3.2 EXECUTIVE SERVICES AVAILABLE TO A DRIVER 


Once a driver is given control following an I/O interrupt or by the 
Executive itself, a number of Executive services are available to the 
driver. These services are discussed in detail in Chapter 7. 


However, four Executive services merit special emphasis because 
virtually every driver in the system uses them: 


1. Get Packet (SGTPKT) 
2. Create Fork Process (SFORK) 


3. I/0 Done ($IODON or SIOALT) 


3.2.1 Get Packet (SGTPRKT) 


The Executive, after it queues an I/O Packet, calls the appropriate 
driver at its I/O initiation entry point. The driver then immediately 
calls the Executive routine $GTPKT to obtain work.* If work is 
available, SGTPKT delivers to the driver the highest-priority, 
executable I/O Packet in the driver's I/O queue, and sets the _ SCB 
Status to busy. If the driver's I/O queue is empty or if the driver 


3) 


EXECUTIVE SERVICES AVAILABLE TO A DRIVER 


is busy, SGTPKT returns a no-work indication. 


If the SCB related to the device is already busy, S$GTPKT so informs 
the driver, and the driver immediately returns control to the 
Executive. 


Note that, from the driver's point of view, no distinction exists 
between no-work and SCB busy, because an I/O operation cannot be 
initiated in either case. 


3.2.2 Create Fork Process (SFORK) 


Synchronization of access to shared data bases is accomplished by 
creating a fork process. When a driver needs to access a shared data 
base, it must do so as a fork process; the driver becomes aé_e fork 
process by calling SFORK. The SCB contains preallocated storage for a 
5-word fork block. See Section 4.4.5 for a description of the fork 
block. Section 1.3.3 contains details on SFORK. After SFORK is 
called, a routine is fully interruptable (priority 0), and its access 
to shared system data bases is strictly linear. 


3.2.3 I/0 Done (SIODON or SIOALT) 


At the completion of an I/O request, the subroutines SIODON or SIOALT 
perform a number of centralized checks and additional functions: 


® Store status if an IOSB address was specified 

@® Set an event flag if one was requested 

@ Determine whether a checkpoint request can now be honored 
@® Determine whether an AST should be queued 


SIODON and SIOALT also declare a significant event, reset the SCB_ and 
device unit status to idle, and release the dynamic storage used by 
the completed I/O operation. 


* An exception is a driver that handles special user buffers. Such a 
driver must call certain other Executive routines before calling 
SGTPKT. See Section 4.4.4 for a description of the UC.QUE bit. 
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PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER 


Chapters 2 and 3 give overviews of data structures and Executive 
services, respectively. This chapter summarizes programming 
Standards, presents overviews of programming requirements for 
user-written driver code and data, and gives details of the data 


structures and driver code. Executive services are covered in Chapter 
des 


4.1 PROGRAMMING STANDARDS 


I/O drivers function as integral components of the P/OS Executive, and 
this manual enables you to incorporate I/O drivers into your system. 
User-written drivers must follow the same conventions and protocol as 
the Executive itself if they are to avoid complete disruption of 
system service. Failure to observe the internal conventions’ and 
protocol that are described fully in Chapter 1 can result in poor 
service and reductions in system efficiency. 


The programming conventions used by P/OS system components are 
identical to those described in Appendix E of the PDP-11l MACRO-11] 


Language Reference Manual. DIGITAL urges you to adhere to _ these 
conventions. 


4.1.1 Programming Protocol Summary 


Drivers are required to adhere to the following internal conventions 
when processing device interrupts: 


1. Registers R4 and R5 are available; any other registers must 
be saved and restored. 


PROGRAMMING STANDARDS 


2. Processing at the priority of the interrupting source should 
be minimized and kept well under 500 usecs. On Professional 
Series hardware, all devices interrupt at processor priority 
4 and, as a result, processing at device priority is 
equivalent to processing at priority 7 with all pending 
interrupts (including the clock) locked out. The interrupt 
arbitration described in the "Professional 300 Series 
Technical Manual" only addresses which of the interrupts is 
subsequently serviced at priority 4 when the processor drops 
its priority to 0. 


3. Kernel APR 6 mapping must be preserved by the interrupt 
service routine if needed to map additional driver code or 
data buffers. | 


4. Only a fork process, which by definition is in system. state, 
may modify a system data base or examine dynamic system data 
structures such as the installed task directory (the STD). 


5. A fork process has unrestricted access to APR 6, and RO-R5. 


6. Complex drivers and system processes that require extended 
periods of processing at system state should consider 


reforking to allow other system processes’ execution time. 
These other system processes could, for example, perform 
clock-related and I/O completion-related processing. Care 


must be exercised that any additional context is preserved if 
required, since only R4, R5 and APR 5 mapping are _ preserved 
across the fork. As always, "double forking" must not occur; 
it is avoided by either uSing an interlock protocol on the 
forkblock, or through the use of a separate forkblock 
allocated from primary pool. 


4.1.2 Accessing Driver Data Structures 


All the driver data structure elements have symbolic offsets. Because 
the physical offset values may vary from one version of the Executive 
to another, your user-written driver code should always use the 
symbols to access the elements. | 


Accordingly, your driver code should not step from one structural . 
element to another (relying on the juxtaposition of data structures 
and individual words in a data structure) but should access’ each 
element by symbolic offset. On the other hand, it is a common coding 
practice to assume that zero offsets (particularly link pointers’ such 
as D.LNK) will remain zero. This assumption allows the saving of one 
word per instruction by substituting an instruction such as MOV 
(R3),R3 for MOV D.LNK(R3),R3. DIGITAL recognizes that such practices 
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are followed and consequently attempts to keep such offsets zero. 


4.2 OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER DATA BASES 


You should create the source code for your user-written driver data 
base in a file separate from that of the driver code. You assemble 
this file to create the driver data base module. If your data base is 
in a separate module, it will be linked to the end of the driver code 
module. If your driver data base is in the same module as that of 
your driver code, it must be at the end of the driver code. 


To create the source code, you need to know, in addition to the 
detailed structures, what ordering and labeling are required. These 
requirements, though not extensive, are important in linking = and 
loading your driver data base. The general coding requirements for 
driver data bases are described in the following subsections. 


4.2.1 General Labeling and Ordering of Data Structures 


When creating a data base, you must specify, for the PROLOD routines, 
two global labels as follows: 


SDAT:: marks the start of the user-written driver data base. 


SEND:: marks the end of the user-written driver data base, 
that is, immediately following the final word of the 
data base. 


If either or both of these labels are not defined, PROLOD cannot 
determine the length of your data base when you attempt to load your 
driver. 


There is no mandatory ordering of the different structures in a driver 
data base. DIGITAL suggests, however, that you place the DCB first, 
followed by the UCB, the SCB(s), the KRB(s), and the CTB. If you do 
not follow this ordering scheme, you must’ specify the starting 
location of the first (or only) DCB as described in Section 4.2.2. 


4.2.2 Device Control Block Labeling 


When writing a driver data base, the PROLOD routines require either 


that the first (or only) DCB be identified by the global label S$DCB:: 
or that the DCB be at the start of the data base. 
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4.2.3 Unit Control Block Ordering 


All the UCBs associated with a specific device control block (DCB) 
must be contiguous with each other and must be of equal length. These 
requirements are necessary because the DCB has only one link to the 
UCBs, and that link is to the first UCB. Two data elements, the UCB 
length and the number of units, are stored in the DCB; they, together 
with the link to the first UCB, are used to locate subsequent UCBs. 
If you do not follow these requirements, no software can access’ the 
UCBs. 


4.2.4 Status Control and Controller Request Blocks 


All user-written drivers that do not need separate storage for 
independent unit context should use the contiguous allocation of the 
KRB and SCB. (For an explanation of when independent unit context is 
required, refer to the discussion of overlapped seek I/O in Section 
1.4.1. Therefore, the KRB and SCB are contiguous and some fields of 
each structure overlap. This arrangement saves space that would be 
required for one SCB for each independent unit. Because only one unit 
can be active at any one time, all units attached to the same 
controller can share the SCB. This arrangement of the KRB and the SCB 
is described in Section 4.4.7. 


4.2.5 Controller Table 


You must define the start of the table of KRB addresses in the CTB 
with the global label S$xxCTB::. Both the INTSVS macro call and the 
Executive PROLOD routines require this label. 
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4.3 OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER CODE 


To create the source code to drive a device, you must perform the 
following steps: 


1. Thoroughly read and understand this manual. 


2. Familiarize yourself in detail with the physical device and 
its operational characteristics. 


3. Determine the level of support required for the device. 
4. Determine actions to be taken at the driver entry points. 


5. Create the driver source code. 


To assist you in generating proper code for your user-written driver 
and to provide a stable user-level interface from one release of the 
system to another, P/OS provides the macro calls listed in Table 4-1. 


The definitions of the system macro calls for drivers are in the 
Executive assembly prefix file RSXMC.MAC. The following subsections 
describe the format of the macro calls and other features of 
user-written driver code. Driver code details (such as labeling 
requirements and entry point conditions) are presented in Section 4.5. 


4.3.1 Generate Driver Dispatch Table Macro Call - DDT$ 


The DDTS macro call facilitates generation of the driver dispatch 
table. The format of the DDTS macro call is as follows: 


DDTS dev,nctrlr,iny,inx,ucbsv,NEW,OPT,BUF 
Table 4-2 lists the arguments of the DDTS macro call. The macro 
constructs the DDT, using as addresses those locations indicated by 
the standard labels. The macro has arguments allowing you to tailor 
some of the standard entry points. The format of the DDT generated by 
the DDTS macro is described in Section 4.5.1. 


Table 4-l: System Macro Calls for Driver Code* 


Macro Name General Functions 


* See Appendix A for Macro definitions. 
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DDTS 


GTPKTS 


INTSVS 


Table 4-2: 


Argument 


dev 


ncetrlr 


iny 


Used conventionally at the start of the driver code 
(1) to allocate storage for and to generate a 
driver dispatch table containing the addresses of 
entry points in the order in which the Executive 
expects them; (2) to generate special global labels 
required by the Executive; (3) to tell the 
Executive PROLOD routines: (a) which controllers 
the driver supports, (b) how many interrupt vectors 
each controller supports, and (c) the association 
between the interrupt vectors and the driver 
interrupt entry points; and (4) to generate default 
controller and unit status change entry point 
procedures (for on-line and off-line transitions) 


Used at the I/O initiator entry point to generate 
the call to the S$GTPKT routine and to generate code 
to save the address of the currently active unit's 
UCB 


Used at an interrupt entry point to conditionally 
generate a call to the SINTSV routine and to 
generate code to load the UCB address of the 
interrupting device into R5 


DDT$ Macro Call Arguments 


Meaning 


is the 2—-character device mnemonic. (Optional, used 
to generate entry point symbol names such as a S$xxINI 
where dev=xx.) 


is the number of controllers that the driver services 
(counting from 1). 


allows the definition of no interrupt entry point or 
multiple interrupt entry points. If you leave the 
argument null, the macro generates as the interrupt 
entry point address the location defined by the 
conventional label SINT. 


If you specify NONE, no interrupt entry point is 
generated for the controller. 


inx 


ucbsv 


BUF 
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If you specify an argument list of the form <aaa,bbb>, 
the macro generates multiple cells containing 
addresses defined by unconventional labels of the form 
Saaa and Sbbb. This. latter mechanism allows you to 
define multiple interrupt entry points in the driver. 
For example, the argument list <INP,OUT> generates two 
interrupt address labels of the form SINP and _ SOUT, 
the typical names used by drivers with two interrupt 
entry points. 


uses an alternate I/O initiation entry point address 
label instead of the conventional INI form. If you 
specify inx, the macro uses as the only I/O initiation 
entry point address the location defined by the label 
inx. 


Strictly speaking, this argument is not needed on P/OS 
systems and can not be used directly if a given 
controller can support parallel operations on multiple 
units simultaneously. If this argument is non-blank, 
a table of "nctrlr" words in length is generated to 
contain the controller index to UCB mapping of a per 
controller I/O operation in progress. As ae result, 
the macro does not allocate the space for the table of 
UCB addresses. For guidelines on specifying this 
argument, refer to Section 4.3.4. 


If this argument is blank, then the DDT powerfail, 
controller status change, and the unit status change 
entry points are NOPed. 


required if the driver performs buffered input = and 
output. The entry point DEA: is generated. 


OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER CODE 


4.3.2 Get Packet Macro Call — GTPKTS 


The GTPKTS macro call standardizes use of the Executive SGTPKT 
routine, which retrieves an I/O packet for the driver to process. 
The format of the GTPKTS macro call is as follows: 


GTPKTS 


dev,nctrlr,addr,ucbsv,suc 


The description of the arguments appears in Table 4-3. 


Table 4-3: 


Argument 


dev 


netrir 


addr 


ucbsv 


suc 


GTPKTS Macro Call Arguments 


Meaning 


is the 2-character device mnemonic (optional). 


is the number of controllers that the driver services 
(counting from 1). 


is the local label defining the location at which to 
continue execution if there is no I/O packet 
available. A driver typically executes a RETURN 
instruction when the S$GTPKT routine indicates that 
there is no I/O packet to process. If you leave this 
argument null, therefore, the macro generates a RETURN 
instruction. 


Strictly speaking, this argument is not needed on P/OS 
systems and can not be used directly if a given 
controller can support parallel operations on multiple 
units simultaneously. If this argument is non-blank, 
a table of "nctrlr" words in length is generated to 
contain the controller index to UCB mapping of a per 
controller I/O operation in progress. The macro’ then 
generates code to load the pointer S.OWN with the 
address of the UCB returned by SGTPKT. For guidelines 
on using the argument, refer to Section 4.3.4. 


indicates single unit controller. If you are writing 
a driver that supports a controller type such as the 
LPl1l, to which only a single unit can be attached, you 
should specify this argument (any character(s) except 
null). If you specify this argument, you should 
ensure that the offset K.OWN/S.OWN in the KRB(s) of 
your driver data base points to the UCB(s) of the 
unit(s) to which the controller(s) is attached. Thus, 
the macro does not generate code that stores the UCB 
address in the KRB for a device that has only one UCB 
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per KRB. 


If your driver has multiple units attached to the same 
controller, you should leave this argument null. The 
macro will then generate code to store the UCB address 
of the unit to process in the SCB or SCB/KRB. 


Note that for non-contiguous SCB/KRB configurations, 
the UCB is stored in K.OWN when the controller request 
is granted, depending on controller characteristics 
(see SROCNC and SROCND in MDSUB). 


This macro call generates the call to the Executive SGTPKT routine. 
You should place it at the I/O initiation (INI) entry point because 
the SGTPKT routine is the standard manner for a driver to receive work 
From the Executive. When the driver receives control at its INI entry 
point, the Executive has loaded R5 with the address of the UCB of the 
unit that the driver must service. Because of the code the macro call 
generates, the driver immediately calls SGTPKT, which can set the C 
bit to indicate that no work iS pending. The call additionally 
generates the BCS instruction that returns control to the calling 
routine when there is no_ work. If you specify an address as the 
"addr" argument in the macro call, it is used as the destination of 
the BCS instruction. The address is typically that of a RETURN 
instruction, but does not have to be. Eventually the driver must 
execute a RETURN to the system. 


The S$GTPKT routine indicates that the driver has an I/O packet to 
process by clearing the C bit. Therefore, when the test of the BCS 
instruction is false, execution continues inline and the driver can 
process the I/O packet that the Executive queued to it. The SGTPKT 
routine leaves information in the driver registers to enable the 
driver to process the request. Refer to the description of the $GTPKT 
routine and the GTPKTS macro listing in Chapter 7. 


4.3.3 Interrupt Save Macro Call - INTSVS 


You should specify the INTSVS$ macro call at each interrupt entry point 
in the driver. The format of the INTSVS macro call is as follows: 


INTSVS dev,pri,nctrlr,pswsv,ucbsv 


The arguments of the call are described in Table 4-4. The macro 
generates the code to load R5 with the UCB address of the current 
controller owner, given the controller index is in R4 (R4 is not 
modified by macro). Note that R5 may be zero in case of either an 
unexpected interrupt (e.g., no current I/O operation), or an interrupt 
as a result of a parallel operation on the same controller. (For 
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example, an overlapped seek completing after a data transfer 
completion.) In general, for configurations which support overlap seek 
it is the driver's responsibility to differentiate between a transfer 
function completion interrupt from a control function completion 
interrupt. 


Table 4-4: INTSVS Macro Call Arguments 


Argument Meaning 
dev is the 2-character device mnemonic (optional). 
pri not used. 
ncetrlir is the number of controllers that the driver services 


(counting from 1). 


pswsw Leave this argument null; it has no effect. It is an 
anachronism, and must be positionally present if ucbsv 
is specified. 


ucbsv Strictly speaking, this argument is not needed on P/OS 
systems and can not be used directly if a given 
controller can support parallel operations on multiple 
units simultaneously. If this argument is non-blank, 
a table of "nctrlr" words in length is generated to 
contain the controller index to UCB mapping of a per 
controller I/O operation in progress. The macro 
generates code which uses the controller’ index 
returned in R4 by SINTSI to index into a UCB table to 
load the UCB address of the interupting device into 
R< 


4.3.4 Usage of UCBSV Argument in Macro Calls 


The DDTS, GTPKTS, and INTSV$S macro calls allow you to specify an 
argument (ucbsv) that uses an alternate technique to map the 
controller index to a UCB address. P/OS does not need to utilize 
the ucbsv argument. The argument ucbsv in the DDTS macro allocates 
ncetrlr words of storage (one word for each controller that the 
driver supports) and labels the first word ucbsv:. This table 
contains the address of the unit control block of the interrupting 
devices for each controller. The GTPKTS macro updates table entries 
at I/O initiation and INTSVS references this table to retrieve the 
UCB address. 
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If you specify the argument ucbsv in the GTPKT$ macro call, it must 
be the same label you supplied for the ucbsv argument in the DDTS 
and INTSVS macro calls. The macro generates code to move the UCB 
address returned by SGTPKT to the correct location in the table 
Starting at the label ucbsv. 


If you specify the argument ucbsv in the INTSVS macro call, it 
should be the same label you supplied for the ucbsv argument in the 
DDTS and GTPKTS macro calls. The macro uses ucbsv to locate the UCB 
address of the interrupting unit, and then generates code to load 
the address into R5. 


4.3.5 Driver Entry Points for PROLOD and PROUNL 


A driver that requires additional initialization and completion 
Functions can define two entry points by labels of the form S$LOA and 
SUNL. Because these two labels do not appear in the DDT itself, 
their format is fixed; you must use the exact format in your driver 
code. When you load the driver, the PROLOD routines check for the 
SLOA entry point. 


The driver is entered, once per UCB, at the SLOA entry point at 
priority zero. At this stage, the driver data base has been loaded 
and pointers have been relocated. The driver is mapped through APR 
5, and the following registers are set up: 


R3 Controller index (undefined if S.KRB = 0) 
R4 - Address of the status control block 
R5 - Address of the unit control block 


The driver may use all the registers. When you unload the driver, 
the PROUNL routine calls it at the SUNL entry point with the same 
conditions. These two entry points in the driver are independent of 
the controller and unit status change entry points used by the 
Executive. That is, the two entry points S$LOA and SUNL are used for 
initialization and at driver load and unload time and not at on-line 
and off-line status change time. Note that SUNL is called only when 
all controllers and units are offline. The database is removed and 
is reused on subsequent reloads. 


4.4 DRIVER DATA STRUCTURE DETAILS 


The following elements in the I/O data structure are of concern to 
the programmer writing a driver: 
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1. The I/O packet 
2. The DCB 
3. The UCB 
4. The SCB 
5. The KRB 
6. The CTB 


The I/O data structure, and the control blocks listed previously in 
particular, contain an abundance of data pertaining to input/output 
operations. Drivers themselves are involved with only a _ subset of 
the data. 


NOTE 


Except where explicitly noted otherwise, all unused 
bits, fields, and words in all driver data base 
structures are reserved for DIGITAL system use and 
expansion. 


In the following descriptions, most data fields (words or bytes) are 
classified by one of five descriptions. Two items in_- each 
description indicate: 


@e Whether the field is initialized in the data-structure 
source, and 


@ What sort of access the driver has to the field during 
execution 


The five descriptions are: 


<initialized, not referenced> 
This field is supplied in the data-structure source code, 
and is not referenced by the driver during execution. 


<initialized, read-only> 
This field is supplied in the data-structure source code, 
and may be read by the driver. 


<not initialized, read-only> 
Either an agent other than the driver establishes’ this 
field, or the driver sets it up once and thereafter 
references it read-only. 

<not initialized, read-write> 
Either the driver or some other agent establishes’ this 
field, and the driver may read it or write over it. 
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<not initialized, not referenced> 
This field does not involve the driver in any way. 
These five descriptions cover most of the fields in the control 
blocks described in this section. No system software or hardware 


checks or enforces any of the access’ described. Exceptions are 
noted in the text. 


4.4.1 The I/O Packet 


Figure 4-1 shows the layout of a control function I/O Packet, and 
Figure 4-2 shows the layout of a transfer function I/O Packet. Both 
are constructed and placed in the driver I/O queue by QIO directive 
processing, and subsequently delivered to the driver by a call to 
SGTPKT. The DPB from which the I/O Packet is generated is 
illustrated in Section 4.4.2. QIO directive processing dynamically 
builds the I/O packet from the data in the DPB. Fields in the I/O 
Packet (see the following text) are classified as: 

@® Not referenced, 

@ Read-only, or 

@ Read-write. 
IT. LNK 

Driver access: 

Not referenced. 


Description: 


Links I/O Packets queued for a driver. A zero ends the 
chain. The listhead is in the SCB (S.LHD). 


I.EFN 
Driver access: 
Not referenced. 
Description: 
Contains the event flag number as copied by QIO directive 
processing from the requester'’s DPB. Bit O<200> indicates 


a virtual function. 


I.PRI 
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Driver access: 
Not referenced. 
Description: 


Priority copied from the TCB of the requesting task. 


Figure 4-1; 
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I/O Packet Format - Control Function 


L.UNK 


ILPRI Vy) rN 
|.EFN 


1.TCB 


I.LN2 


|.UCB 


|.FCN 


|.10SB 


|.AST 


IL.PRM 


|l.AADA 


|.AADA+2 


Link to next 1/O a Sa 


Device 
parameters 
(control functions) 


PS 


Attachment Descriptor Pisintek 


Attachment Descriptor Pointer 


Figure 4-2: 
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I/O Packet Format - Transfer Function 


L.LNK 


I.PRI 
|.EFN 


1.TCB 


I.LN2 


1.UCB 


IL.FCN 


1.1OSB 


LAST 


|.PRM 


|.AADA 


|. AADA+2 


ee 


Virtual address of AST service routine 


Relocation BIAS of buffer 


Displacement of buffer (+140000) 


Device 
parameters 


(transfer functions) 


P4 


P5 
Attachment Descriptor Pointer 


P1 assumed to be buffer virtual address 
P2 assumed to be buffer size in bytes 


Attachment Descriptor Pointer 
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I.TCB 
Driver access: 


Not referenced usually. Referenced at I/O cancel. 


Description: 


TCB address of the requesting task. 


I.LN2 
Driver access: 
Not referenced. 
Description: 


Contains the address of the second word of the LUT entry in 
the task header to which the I/O request is directed, if 
even. Also, for virtual functions, if even, the task 
region, and consequently the header, was locked in memory 
by incrementing the appropriate I/O counts. For open files 
on file-structured devices, this word contains the address 
of the Window Block. T&£ odd, it is the window block 
pointer; otherwise zero. 


I.UCB 
Driver access: 


Not referenced by conventional driver; frequently 
referenced by drivers that use $GSPKT and maintain parallel 
active unit context UCBS rather that the _ SCBs, and 
therefore have a "many to one" UCB to SCB configuration. 


Description: 
Contains the address of the unit to which I/O is to be 
directed. I.UCB is the address of the Redirect UCB if the 
starting UCB has been subject to a Redirect command. The 
field is referenced by the SGTPKT routine. 
IT.FCN 
Driver access: 


Read-only. 


Description: 


I.IOSB 
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Contains the function code for the I/O request. Tt 
consists of two bytes. The high-order byte contains the 
function code; the low-order byte contains modifier 


(subfunction) bits. During predriver initiation the 
Executive compares the function code with a function: mask 
value in the DCB. The driver interprets the modifier 


(subfunction) bits. 


Driver access: 


Not referenced. Do not touch. Driver specifies status at 
I/O completion in registers to S$IODON or SIOFIN. The 
region containing the IOSB is not guaranteed to be memory 
resident, except at predriver initiation time (see UC.QUE). 


Description: 


IT.AST 


I.IOSB contains the virtual address of the I/O Status Block 
(IOSB), if even, or zero if one was not specified. 


I. IOSB+2 and I.IOSBt4 contain the address doubleword for 
the IOSB if I.IOSB is even and nonzero (see Section 7.4 for 
a detailed description of the address doubleword. 


Driver access: 


Not referenced. 


Description: 


I.PRM 


Contains the virtual address of the AST Service routine to 
be executed at I/O completion. If no address is specified, 
the field contains zero. 


Driver access: 


Read-write. 


Description: 


Device-dependent parameters constructed from the last s1x 
words of the _ DPB. Note that if the I/O function is a 
transfer (refer to the description of D.MSK in Section 
4.4.3, the buffer address (first DPB device-dependent 
parameter) is translated to an equivalent address 
doubleword. Therefore, the virtual buffer address, which 
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occupied one word in the DPB, occupies two words in I.PRM. 
As a result, all other parameters in I.PRM are shifted by 
one word so that device-dependent parameter n is copied to 
I.PRM +(2¥*n)+2. 


Most DIGITAL-supplied drivers treat these words as a 


read/write storage area after their initial contents have 
been used. 


When the last word of the device-dependent parameters is 
nonzero, the value can have one of several special meanings 
to the Executive. For example, if the value is nonzero and 
the I/O function is marked "virtual," the Executive assumes 
that the value is a block locking word. Therefore, if the 
driver uses the word, it should restore its contents before 
calling S$IODON. 


Driver access: 


Not referenced; maintained by the Executive transparently 
to the driver. 


Description: 


4.4.2 


Two pointers, each to an attachment descriptor block of the 
region in which the task I/O buffer resides. These 
pointers account for I/O by region and enable the Executive 
to lock a region to make it noncheckpointable while I/O is 
in progress, and to unlock a region after I/O completes. 


The QIO Directive Parameter Block (DPB) 


The QIO DPB is constructed as shown in Figure 4-3. Usually drivers 


never 


access the DPB; the information is supplied here for general 


reference. 
The parameters in the DPB have the following meanings: 


Length (required): 


The length of the DPB, which for the QIO directive is always 
fixed at 12 words. 


DIC (required) : 


Directive Identification Code. For the QIO directive, this 
is l. For QIOW it is 3. 
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Q.IOFN (required): 


The code of the requested I/O function (0 through 31). 


. 
Q.1IOFN Function code Z 


Q.IOPL +0 14 
2 
+4 Device- 
dependent 
+6 parameters 
+10 
#12 


ZK-255-81 


Figure 4-3: QIO Directive Parameter Block (DPB) 


Modifier: 

Device-dependent modifier bits. 
Reserved: 

Reserved byte; must not be used. 
O.IOLU (required): 


Logical Unit Number. 
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Q.IOPR: 


Request priority. Ignored by P/OS but space must be allocated 
for IAS compatibility. 
Q.IOEF (optional): 


Event flag number. Zero indicates no event flag. 


Q.IOSB (optional): 


This word contains a pointer to the I/O status block, which is 
a 2-word, device-dependent I/O-completion data packet formatted 
as: 
Byte 0 

I/O status byte. 


Byte l 


Augmented data supplied by the driver. 


Bytes 2 and 3 


The contents of these bytes depend on the value of byte 0. 
If byte 0 = 1, then these bytes usually contain the 


processed byte count. If byte 0 does not equal O, then 
the contents are device-dependent. 
Q.IOAE (optional): 


Address of the I/O done AST service routine. 


Q.IOPL 


Up to six parameters specific to the device and to_ the I/O 
function to be performed. Typically, for data transfer 
functions, the following four are used: 

e Buffer address 

@® Byte count 

@ Carriage control type 


@ Logical block number 


The fields for any optional parameters not specified must be filled 
with zeros. 


DRIVER DATA STRUCTURE DETAILS 


4.4.3 The Device Control Block (DCB) 


Figure 4-4 is a schematic layout of the DCB. The DCB describes’ the 
static characteristics of a device controller and the units attached 
to the controller. All fields must be specified. 


: 
: 
; 
: 
: 
: 
D.PCB 34 


Address of partition control block 


ZK-256-81 


Figure 4-4: Device Control Block 
The fields* in the DCB are described as follows: 
D.LNK (link to next DCB) 


Driver access: 


* Parenthesized contents following the symbolic offset indicate the 
value to be initialized in the data base source code. 
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Initialized, not referenced. 


Description: 


Address link to the next DCB. If this cell is in the last 
(or only) DCB, you should set its value to zero. If you 
are incorporating more than one user-written driver at one 
time, then this field should point to another DCB in a DCB 


chain, which is terminated by a value of zero. 
D.UCB (pointer to first UCB) 


Driver access: 


Initialized, not referenced. 


Description: 


Address link to the U.DCB field of the first, and possibly 
the only, unit control block associated with the DCB. For 
a given DCB, all UCBS are in contiguous memory locations 
and must all have the same length. 


D.NAM (ASCII device name) 
Driver access: 


Initialized, not referenced. 


Description: 


Generic logical device name in ASCII by which device units 
are mnemonically referenced. 


D.UNIT (unit number range) 


Driver access: 


Initialized, not referenced. 


Description: 


Unit number range for the device. The low-order byte 
contains the lowest logical unit number; the high-order 
byte contains the highest logical unit number. This’ range 
covers those logical units available to the user for device 
assignment. Typically, the lowest number is zero or _ one, 


and the highest is n-l, where n is the number of 
device-units described by the DCB. 


D.UCBL (UCB length) 
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Driver access: 
Initialized, not referenced. 
Description: 


The unit control block can have any length to meet’ the 
needs of the driver for variable storage. However, all 
UCBs for a given DCB must have the same length. The 
specified length must include prefix words (such as U.LUIC 
and U.OWN), if present. 


D.DSP (driver dispatch table pointer) 
Driver access: 
Not referenced. 
Description: 


Address of the driver dispatch table, which is’ located 
within the driver code. (When the Executive wishes to 
enter the driver at any of the entry points contained in 
the driver dispatch table, it accesses D.DSP, locates the 
appropriate address in the table, and calls the driver at 
that address.) 


D.MSK (driver-specific function masks) 
Driver access: 
Initialized, not referenced. 
Description: 


Eight words, beginning at D.MSK, are critical to the proper 
functioning of a device driver. The Executive uses these 
words to validate and dispatch the I/O request specified by 
a QOIO directive. The following description applies only to 
nonfile-structured devices.* Four masks, with two words per 
mask, are described by the bit configurations that you 
establish for these words: 


1. Legal function mask 


* Although no DIGITAL publication describes writing drivers for 
file-structured devices (drivers that interface with FI1ACP), you 
could write a disk driver by using a DIGITAL-~Supplied driver as a 
template. 
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2. Control function mask 

3. No-op function mask 

4. ACP function mask 
The QIO directive allows for 32 possible I/O functions. 
The masks, as stated, are filters to determine validity and 
I/O requirements for the subject driver. 
The Executive filters the function code in the I/O request 


through the four masks. The I/O function code is the 
high-order byte of the function parameter issued with the 


QIO directive. The decimal representation of that 
high-order byte is equivalent to the decimal bit number of 
the mask. Tf you want the function to be true in one of 


the four masks, you must set the bit in that mask in the 
position that numerically corresponds to the function code. 
For example, the code for IO.RVB is 21 (octal) and its 
decimal representation is 17. If you want IO.RVB to be 


true for a mask, therefore, you must set bit number 17 in 
the mask. 


The masks are laid out in memory in two 4-word groups. 
Each 4-word group covers 16 function codes. The first 4 
words cover the function codes 0 through 15; the second 4 
words cover codes 16 through 31. Below is the exact layout 
used for the driver example in Chapter 8. 


» WORD 177477 >LEGAL FUNCTION MASK CODES 0-15. 

e WORD 70 ;CONTROL FUNCTION MASK CODES 0-15. 

» WORD 0 ;NO-OP FUNCTION MASK CODES 0-15. 

» WORD 177200 s>ACP FUNCTION MASK CODES 0-15. 

e WORD 377 ;LEGAL FUNCTION MASK CODES 16.-31. 

e WORD 0 *CONTROL FUNCTION MASK CODES 16.-31l. 
e WORD 0 ;NO-OP FUNCTION MASK CODES 16.-31. 

e WORD 377 ;ACP FUNCTION MASK CODES 16.-3l. 


The Executive filters the function code through the mask 
words sequentially as follows: 


Legal Function Mask: 


Legal function values have the corresponding bit position 
in this word set to 1. Function codes that are not legal 
are rejected by QIO directive processing, which returns 
IE.IFC in the I/0 status block, provided an IOSB address 
was specified. 
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Control Function Mask: 


If any device-dependent data exists in the DPB, and this 
data does not require further checking by the QIO directive 
processor, the function is considered to be ae control 
function. Such a function allows QIO directive processing 
to copy the DPB device-dependent data directly into the I/O 
Packet. 


No-op Function Mask: 


A no-op function is any function that is considered 
successful as soon as it is issued. If the function is a 
no-op, QIO directive processing immediately marks’ the 
request successful; no additional filtering occurs. 


ACP Function Mask: 


If a function code is legal but specifies neither a control 
function nor a no-op, then it specifies either an ACP 
function or a transfer function. If a function code 
requires intervention of an Ancillary Control Processor 
(ACP), the corresponding bit in the ACP function mask must 
be set. ACP function codes must have a value greater than 
Ute 


In the specific case of read-write virtual functions, the 
corresponding mask bits may be set at your option. If the 
corresponding mask bits for a read-write virtual function 
are set, QIO directive processing recognizes that a 
File-oriented function is being requested to a 
nonfile-structured device and converts’ the request to a 
read-write logical function. 


This conversion is particularly useful. Consider a 
read-write virtual function to a specific device: 


1. If the device is file-structured and a file is open on 
the specified LUN, the block number specified is 
converted from a virtual block number in the file to a 
logical block number on the medium. Moreover, the 
request is queued to the driver as a read-write logical 
function. 


2. If the device is file-structured and no file 1S open on 
the specified LUN, then an error is returned and no 
further action is taken. 
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3. If the device is not file-structured, then the request 
is simply transformed to a read-write logical function 
and is queued to the driver. (The specified block 
number is unchanged.) 


Transfer Function Processing: 


Finally, if the function is not an ACP function, then it is 
by default a transfer function. All transfer functions 
cause the QIO directive processor to check the specified 
buffer for legality (that is, inclusion within the address 
space of the requesting task) and proper alignment (word or 
byte). In addition, the processor checks the number of 
bytes being transferred for proper modulus (that is, 
nonzero and a proper multiple). All transfer functions 
except IO.WLB and IO.WVB are assumed to require Read and 
Write access to the buffer region, and are access checked 
accordingly. By convention, the first user-supplied 
parameter is the buffer address and the second is the byte 
count. 

Creating Mask Words: 


Creating function mask words involves the following five 
steps: 


1. Establish the I/O functions available on the device for 
which driver support is to be provided. 


2. Build the Legal Function mask: Check the standard P/OS 
function mask values in Table 4-6 for equivalencies. 
Only the IO.KIL function is mandatory. IO.ATT and 
IO.DET functions, if used, must have the P/OS system 
interpretation. DIGITAL suggests that functions having 
an P/OS system counterpart use the P/OS code, but this 
is required only when the device is to be used in 
conjunction with an ACP. From the supported function 
list in Table 4-5, you can build the two Legal Function 
mask words. 


3. Build the Control Function mask by asking: 


Does this function carry a standard buffer address and 
byte count in the first two device-dependent parameter 
words? 


If it does not, then either it qualifies as a control 
function or the driver itself must effect the checking 
and conversion of any addresses to the format required 


by the driver. See Section 8.1 for an example of a 
driver that does this. (Buffer addresses in standard 
format are automatically converted to Address 
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Doubleword format.) 


Control functions are essentially those functions whose 
DPBs do not contain buffer addresses or counts. 


4. Create the No-op Function mask by deciding which legal 
functions are to be no-oOp. Typically, for 
compatibility with File Control Services (FCS) or 
Record Management Services (RMS) on nonfile-structured 


devices, the file access/deaccess functions are 
selected as legal functions, even though no specific 
action is required to access or deaccess a 


nonfile-structured device; thus, the access/deaccess 
functions are no-op. 7 


5. Finally, include the ACP functions Write Virtual Block 
and Read Virtual Block for those drivers that support 
both read and write. (Include only one related ACP 
function if the driver supports only read or write). 
Other ACP functions that might be included fall into 
the nonconventional driver classification and are 
beyond the scope of this document. 


D.PCB (0) 
Driver access: 


Initialized, not referenced. 
Description: 


Address of the driver's Partition Control Block (PCB). The 
driver data base source must initialize the address to 
zero. The DCB can be extended by adding words after D.PCB. 
A PCB exists for every partition ina system. A driver PCB 
describes the partition in which it resides. 


The Executive uses D.PCB together with D.DSP (the address 
of the driver dispatch table) to determine a driver is in 
memory. Zero and nonzero values for these two pointers 
have the meanings shown in Figure 4-5. 


4.4.3.1 Establishing I/O Function Masks - Table 4-5 is supplied to 
assist you in determining the proper values to set in the function 
masks. The mask values are given for each I/O function used by 
DIGITAL~supplied drivers. The bit number allows you to determine 
which mask group to use: for bits numbered 0 through 15, use the 
mask value for a word in the first 4-word group; for bits numbered 
16 through 31, use the mask value for a word in the second 4-word 
group. 
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D.PCB: 


Loadable 
driver, 


(not 


Beni possible) 


memory 


Loadable 
driver, 
in memory 


(not 
possible) 


#0 


Figure 4-5: D.PCB and D.DSP Bit Meanings 


Of the function mask values listed in Table 4-5, only I0O.KIL is 
mandatory and has a fixed interpretation. However, if IO.ATT and 
IO.DET are used, they must have the standard meaning. (Refer to the 
Professional Developer's Tool Kit Reference Manual) Order no. 
AA-Y660A-TK for a description of standard 1/0 functions.) If QIO 
directive processing encounters a function code of 3 or 4 and the 
code is not no-op, QIO assumes that these codes represent Attach 
Device and Detach Device, respectively. The other codes are 
suggested but not mandatory. You are free to establish all other 
function-code values on nonfile-structured devices. However, the 
mask words must still reflect the proper filtering process. 


If you are writing a driver for a file-structured device, you must 
establish the standard function mask values of Table 4-5. 


To determine the proper bit masks for disks, tapes, and unit record 
devices (such as terminals, card readers, line printers, paper tape 
punches/readers), use Table 4-6, Table 4-7, and Table 4-8 as guides. 


Table 4-5: 
Bit Mask 

Value 

0 1 
1 2 
2 4 
3 10 
4 20 
5 40 
6 100 
7 200 
8 400 
9 1000 
10 2000 
11 4000 
12 10000 
13 20000 
14 40000 
15 100000 
16 1 
17 2 
18 4 
19 10 
20 20 
21 40 
22 100 
23 200 
24 400 
25 1000 
26 2000 
27 4000 
28 10000 
29 20000 
30 40000 
31 100000 
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Related 
Symbolic 


IO.KIL 
IO.WLB 
IO.RLB 
IO.ATT 
IO.DET 


IO.FNA 
IO.ULK 
IO.RNA 
IO.ENA 
IO.ACR 
IO.ACW 
IO.ACE 
IO.DAC 
IO.RVB 
IO.WVB 
IO.EXT 
IO.CRE 
IO.DEL 
IO.RAT 
IO.WAT 
IO.APC 


IO.APV 


Mask Values for Standard I/O Functions 


I/O 
Function 


Cancel I/O 

Write Logical Block 
Read Logical Block 
Attach Device 

Detach Device 

General Device Control 
General Device Control 
General Device Control 
Diagnostics 

Find File in Directory 
Unlock Block 

Remove File from Directory 
Enter File in Directory 
Access File for Read 
Access File for Read/Write 
Access File for Read/Write/Extend 
Deaccess File 

Read Virtual Block 
Write Virtual Block 
Extend File 

Create File 

Mark File for Delete 
Read File Attributes 
Write File Attributes 
ACP Control 

Unused 

Unused 

Unused 

Unused 

Unused 

ACP Privileged 

Unused 
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Table 4-6: Mask Word Bit Settings for Disk Drives 


Bit P/OS Related Symbolic 
0 Cc IO.KIL 
1 t IO.WLB 
2 IO.RLB 
3 Cc IO.ATT 
4 Cc IO.DET 
5 Cc LOVSTC 
6 
A sa IO.CLN 
8 sd Diagnostic 
2 a IO.FNA 
10 a TO.ULK 
1i a IO.RNA 
dz a IO.ENA 
i3 a IO.ACR 
14 a IO.ACW 
_ 15 a IO.ACE 
16 a IO.DAC 
17 a IO.RVB 
18 a IO.WVB 
19 a IO.EXT 
20 a IO.CRE 
21 a IO.DEL 
Ze a IO.RAT 
23 a IO.WAT 
24 a ITO.APC 
25 
26 
21 
28 
29 
30 a IO.APV 
31 
t - transfer function, bit set only in legal function mask 
c - control function, bit set in legal and control function masks 
n - no-op function, bit set in legal and no-op function masks 
a - ACP function, bit set in legal and ACP function masks 
Sa - special case, bit set only in ACP function mask, but not legal 
sd - special case, bit set only if diagnostic support in system and 


driver 
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Table 4-7: Mask Word Bit Settings for Magnetic Tape Drives 


Bit P/OS (currently IS.PND) Related Symbolic 
0 Cc IO.KIL 
1 t IO.WLB 
2 t ITO.RLB 
3 Cc IO.ATT 
4 Cc IO.DET 
5 C IO.STC 
6 Cc 
7 sa IO.CLN 
8 sd Diagnostic 
9 a IO.FNA 
10 IO.ULK 
11 ITO.RNA 
12 n IO.ENA 
13 a IO.ACR 
14 a IO.ACW 
15 a IO.ACE 
16 a ITO.DAC 
17 a IO.RVB 
18 a ITO.WVB 
19 a IO.EXT 
20 TO.CRE 
21 IO.DEL 
22 a IO.RAT 
23 IO.WAT 
24 a IO.APC 
25 
26 
27 
28 
29 
30 a IO.APV 
3] 
t - transfer function, bit set only in legal function mask 
Cc - control function, bit set in legal and control function masks 
n - no-op function, bit set in legal and no-op function masks 
a - ACP function, bit set in legal and ACP function masks 
sa - special case, bit set only in ACP function mask, but not legal 
sd - special case, bit set only if diagnostic support in system and 


driver 
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Table 4-8: Mask Word Bit Settings for Unit Record Devices 


Bit P/OS Related Symbolic 
0 c IO.KIL 
1 t IO.WLB 
2 t IO’ RLB 
3 c IO.ATT 
4 Cc 10*.DE7 
5 C LO<Stc 
6 
7 sa IO.CLN 
8 sd Diagnostic 
9 a IO.FNA 
10 a IO.ULK 
1l a IO.RNA 
12 a IO.ENA 
13 a IO.ACR 
14 a IO.ACW 
ES a IO.ACE 
16 a IO.DAC 
17 a IO.RVB 
18 a IO.WVB 
19 a IO.EXT 
20 a IO.CRE 
Zi a IO.DEL 
22 a IO.RAT 
23 a IO.WAT 
24 a IO.APC 
25 
26 
27 
28 
29 
30 
37) 
t - transfer function, bit set only in legal function mask 
c - control function, bit set in legal and control function masks 
n - no-op function, bit set in legal and no-op function masks 
a - ACP function, bit set in legal and ACP function masks 
Sa - special case, bit set only in ACP function mask, but not legal 
sd - special case, bit set only if diagnostic support in system and 


driver 
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4.4.4 The Unit Control Block (UCB) 


Figure 4-6 is a layout of the UCB (a variable-length control block). 
One UCB exists for each physical device-unit generated into a system 
configuration. For user-added drivers, this control block is defined 
as part of the source code for the driver data structure. 
The fields* in the UCB are described below: 
U.UAB (0) 
Driver access: 
Initialized, not referenced. 
Description: 
For terminal UCBs only. Reserved. 
U.MUP 
Driver access: 
Not initialized, not referenced. 
Description: 
For terminal UCBs only. 
U.LUIC (0<100200>) 
Driver access: 
Initialized, not referenced. 
Description: 
For terminal UCBs only, and only in multiuser’ systems: the 
logon UIC of the user at the particular terminal. This 
offset must exist for any device on a multiuser system for 


which the DV.TTY bit is set. 
U.OWN (0) 


Driver access: 


Initialized, not referenced. 


* Parenthesized contents following the symbolic offset indicate the 
value to be initialized in the data base source code. 


4-34 


DRIVER DATA STRUCTURE DETAILS 


Description: 


The UCB address of the owning terminal for allocated devices. 


U.UAB! L reserved 1 10 
U.MUP! reserved 6 

. ee : 
U.LUIC reserved 
U.OWN Owning terminal UCB address 
U.DCB Back pointer to DCB 
U.RED Redirect UCB pointer 
st | 
U.UNIT . 
UST2 Unit status Physical unit no. 

. devices 

U.SCB Pointer to SCB 20 
U.ATT TCB address of attached task 22 
U.BUF+2 Buffer address 26 
U.CNT Byte count 30 


orm eewenne = eemenies © eared 0 em eta cement = NEN ent een = mR instants 


U.UCBX 2 | Pointer to the UCB extension in secondary pool | 32 


Device- 


dependent 


| storage | 


1. This offset appears only for terminal devices (that is, devices that have DV.TTY set) 
2. This offset appears only for those devices that have DV.MSD set. 
Figure 4-6: Unit Control Block 
U.DCB (pointer to associated DCB) 


Driver access: 
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Initialized, not referenced. 


Description: 


This word is a pointer to the corresponding device control 
block. Because the UCB is a key control block in the I/O 
data structure, access to other control blocks usually occurs 
by means of links implanted in the UCB. 


U.RED (pointer to start of this UCB (.-2)) 
Driver access: 
Initialized, not referenced. 
Description: 


Contains a pointer to the unit control block to which this 
device-unit has been redirected. The redirect chain ends 
when this word points to the beginning of the UCB itself 
(U.DCB of the UCB, to be precise). 


U.CTL (device-dependent values) 
Driver access: 
Initialized, not referenced. 
Description: 


U.CTL and the function mask words in the device control block 
control QIO directive processing. Figure 4-7 shows the 
layout of the unit control byte. 


The driver data base code statically establishes this bit 
pattern. Any inaccuracy in the bit setting of U.CTL produces 
erroneous I/O processing. Bit symbols and their meanings are 
as follows: 


UC.ALG - Alignment bit. 


Tf this bit is 0, then byte alignment of data buffers is 
allowed (for example, a communications driver). If UC.ALG is 
1, then buffers must be word-aligned (for example, a disk 
driver). 
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U.STS U.CTL 


15 8,7 0 
PE FE 


uc. LGH - Buffer size mask bits for transfer length 


UC.KIL - Unconditional cancel 1/O (1=yes) 
UC.ATT - Attach/detach notification (1=yes) 
UC.PWE - Unconditional call at powerfail (1=yes) 
UC.QUE - Queue to driver bit (1=yes) 
UC.NPR - NPR device bit (1=yes) 


UC.ALG - Alignment (byte or word)(1=no) 


ZK-258-81 
Figure 4-7: Unit Control Byte 


UC.ATT - Attach/Detach notification. 


If this bit is set, then the driver is called when SGTPRKT 
processes an Attach/Detach I/O function. Typically, the 
driver does not need to obtain control for Attach/Detach 
requests, and the Executive performs’ the entire function 


without any assistance from the driver. When the need 
exists, the most common use of UC.ATT is for event 
notification without outstanding I/O. Attachment coupled 


with UC.ATT provides an I/O rundown operation (IO.DET) to 
occur so that the driver can remove this context when the 
issuing task exits - gracefully or otherwise. 


UC.KIL - Unconditional Cancel I/O call bit. 


If set, the driver is called on a Cancel I/O request, even if 
the unit specified is not busy. Typically, the driver is 
called on Cancel I/O only if an I/O operation is in progress. 
In any case, the Executive flushes the I/O queue. 


UC.QUE - Queue to-driver bit. 
If set, the QIO directive processor calls the driver at its 
I/O initiation entry point without queuing the I/O packet. 


After the processor makes this call, the driver is 
responsible FOr the disposition of the I/O packet. 
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U.STS (0) 
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Typically, the processor queues an I/O Packet before calling 
the driver, which later retrieves it by a call to SGTPKT. 


The most common reason for a driver to examine a packet 
before queuing is that the driver employs a special user 
buffer, other than the normal buffer used in a transfer 
request. Within the context of the requesting task, the 
driver must address-check and relocate such a special buffer. 
See Section 8.1 for an example of a driver that does this. 
Use SCKBFR, SCKBFB, OR SCKBFW rather than SACHRO, SACHKB, 
SACHKW, since the later routines do not increment region and 
ACB I/O counts. 


UC.PWF - Unconditional call on loading driver bit. 


If set and the unit is on-line, the driver is always to be 
called when driver is loaded. Driver may then ignore unit 
and controller status changes by simply performing a RETURN 
instruction. The driver, however, can never be unloaded 
without reboot if these entry points are ignored for. the 
online to offline transition. 


UC.NPR - NPR device bit. 


If set, the device is an NPR device. This bit determines the 
format of the 2-word address in U.BUF (details given in the 
discussion of U.BUF below). It is normally cleared. 


UC.LGH - Buffer size mask bits (two bits). 


These two bits are used to check whether the byte count 
specified in an I/O request is a legal buffer modulus. You 
select one of the values below by ORing into the byte a 0, l, 
25 OY. 2. 


00 - Any buffer modulus valid 


O01 — Must have word alignment modulus 
10 - Combination invalid 
11 - Must have double word-alignment modulus 


UC.ALG and UC.LGH are independent settings. 


Driver access: 


Initialized, not referenced. 


Description: 
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This byte contains device-independent status information. 
Refer to the UCBDF$ macro definition in Appendix A. Figure 
4-8 shows the layout of the unit status byte. 


U.ST2 U.UNIT 


15 Se/7 0 
for system use and expansion. 
| US.OFL - Unit offline (1=yes) 


US.RED - Unit redirectable (1=no) 

US.PUB - Unit is public device (1=no) 

US.UMD - Unit attached for diagnostic s (1=yes) 
US.PDF - Privileged diagnostic functions only (1=yes) 
US.MUN - clusterdevice (1=yes) 

US.TRN - unit transition has accured (1=yes) 

US.SIO - stall 1/O to unit (1=yes) 


Figure 4-8: Unit Status Byte 


US.MDM, US.MNT, US.VV and US.FOR apply only to mountable 
devices.* The bit meanings are as follows: 


US.BSY 

If set, device-unit is busy. 

US .MNT 

If set, volume is not mounted. 

US.FOR 

If set, volume is mounted foreign. 

US .MDM 

If set, device is marked for dismount. 
US.VV 


If set, volume is valid from a software viewpoint. 


* If your user-written driver services a mountable device, refer to 
Section 4.5.7 for information on volume valid processing. 
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U.UNIT (unit number) 
Driver access: 
Initialized, read-only. 
Description: 


This byte contains the physical unit number of the 
device-unit serviced by this UCB. If the controller for the 


device supports only a single unit, the unit number is always 
ZeLKO. 


NOTE 
This 1s the physical unit number of the device and 
not the logical unit number. The range of this 
number is from zero to n where n is device-dependent. 
The logical designation DBO: does not necessarily 
imply a zero in this byte. 
U.ST2 (US.OFL) 
Driver access: 
Initialized, not referenced. 


Description: 


This byte contains additional device-independent status 
information. Different parts of the system set and clear 
these bits. The layout of the unit status extension byte is 
shown in Figure 4-9. 

The bit meanings are as follows: 

US .OFL=1 


If set, the device is off-line (that is, not in the 
configuration). This bit should be initialized to l. 


US.RED=2 
If set, the device cannot be redirected. 
US. PUB=4 


If set, the device is a public device. 
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US .UMD=10 
If set, the device is attached for diagnostics. 


US.PDF=20 


If set, this unit can be used for a privileged diagnostic 
function only. 


US.TRN=100 
If set, unit volume status change in progress. 


US .SIO=200 


If set, I/O is stalled typically until volume is reverified. 


U.STS U.CTL 


15 oii 6) 
ee a ne Unused bits are reserved 


Cc for system use and expansion. 


US.MDM - Marked for dismount (1=yes) 
US.FOR - Mounted as foreign volume (O=yes) 
US.MNT - Volume is mounted (1=no) 
US.BSY - Device-unit busy (1=yes) 


Figure 4-9: Unit Status Extension 2 
U.CWl (device-specific characteristics) 
Driver access: 
Initialized, not referenced. 
Description: 


The first of a 4-word contiguous cluster of device 


characteristics information. U.CWl and U.CW4 are 
device-independent, whereas U.CW2 °&#£and U.CW3 are 
device-dependent. The four characteristics words are 


retrieved from the UCB and placed in the requester's buffer 
on issuance of a Get LUN information (GLUNS$) Executive 
directive. It is your responsibility to supply the contents 
of these four words in the assembly source code of the data 
structure. | 


b> 
j 


4l 
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U.CWl is defined as follows. (If a bit is set to 1, the 
corresponding characteristic is true for the device.) 
DV.REC=1 
Record-oriented device 
DV.CCL=2 
Carriage-control device 
DV.TTY=4 


Terminal device. If DV.TTY is set, then the UCB’ contains 
extra cells (for U.LUIC, U.CLI, and optionally U.UAB). 


DV.DIR=10 

Directory device 

DV.SDI=20 

Single directory device DV.SQD=40 
Sequential device 

DV.MSD=100 

Mass Storage device 

DV.UMD=200 

Device supports user-mode diagnostics 
DV.EXT=400 

Unit is on an extended 22-bit controller 
DV.SWL=1000 

Unit is software write-locked 
DV.ISP=2000 

Input spooled device 


DV .OSP=4000 
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Output spooled device 
DV.PSE=10000 


Pseudo device. If this bit is set, the UCB does not extend 
past the U.CWl offset. 


DV .COM=20000 
Device mountable as a communications channel 
DV.F11=40000 
Device mountable as a FILES-11l device 
DV.MNT=100000 
Device mountable* 
U.CW2 (device-specific characteristics) 

Driver access: 
Initialized, read-write. 

Description: 


Specific to a given device driver (available for working 
storage or constants).** 
U.CW3 (device-specific characteristics) 


Driver access: 
Initialized, read-write. 
Description: 


Specific to a given device driver (available for working 


* If your user-written driver services a mountable device, refer to 
Section 4.5.7 for information on volume valid processing and 
privileged ACP functions. 


** An exception is that, for block-structured devices, U.CW2 and U.CW3 
may not be used for working storage. In drivers for block-structured 
devices (disks and DECtape), these two words must be initialized to a 
double-precision number giving the total number’ of blocks on the 
device. Place the high-order bits in the low-order byte of U.CW2 and 
the low-order bits in U.CW3. 
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storage or constants) .* 
U.CW4 (device-specific characteristics) 
Driver access: 
Initialized, read-only. 
Description: 


Default buffer size in bytes. This word is changed by a 
system command (SET with the /BUF keyword). The value in 
this word effects FCS, RMS, and many utility programs. 


U.SCB (SCB pointer) 
Driver access: 
Initialized, read-only. 
Description: 


This field contains a pointer to the status control block for 
this UCB. In general, R4 contains the value in this word 
when the driver is entered by way of the driver dispatch 
table, because service routines frequently reference the SCB. 


U.ATT (0) 
Driver access: 


Initialized, not referenced. 


Description: 


Tf a task has attached itself to the device-unit, this field 
contains its task control block address. 


U.BUF (reserve two words of storage) 


Driver access: 


* An exception is that, for block-structured devices, U.CW2 and U.CW3 
may not be used for working storage. In drivers for block-structured 
devices (disks and DECtape), these two words must be initialized to a 
double-precision number giving the total number of blocks on the 
device. Place the high-order bits in the low-order byte of U.CW2 and 
the low-order bits in U.CW3. | 
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Not initialized, read-write. 


Description: 


U.BUF labels two consecutive words’ that serve as a 
communication region between SGTPKT and the driver. Ifa 
nontransfer function is indicated (in D.MSK), then U.BUF, 


U.BUF+2, and U.CNT receive the first 3 parameter words from 
the I/O Packet. 


For transfer operations, the initial format of these two 
words depends on the setting of UC.NPR in U.CTL. The driver 
does not format the words; all formatting is completed before 
the driver receives control. The format is determined by the 
UC.NPR bit, which is set for an NPR device and reset for a 
program-transfer device. 


The format for program-transfer devices is an address 
doubleword identically formatted to I.IOSB+2 and I.IOSBt4. 


In general, the driver does not manipulate these words’ when 
performing I/0 to a eprogram-transfer device. Instead, it 
uses the Executive routines Get Byte, Get Word, Put Byte, and 
Put Word to effect data transfers between the device and the 
user's buffer. 


The details of the construction of the Address Doubleword 
appear in Chapter 7. 


U.CNT (reserve one word of storage) 


Driver access: 


Not initialized, read-write. 


Description: 


U.UCBX 


Contains the byte count of the buffer described by U.BUF. 
The driver uses this field in constructing the actual device 
request. 


U.BUF and U.CNT keep track of the current data item in _ the 
buffer for the current transfer (except for NPR transfers). 
Because this field is being altered dynamically, the I/O 
Packet may be needed to reissue an I/O operation (for 
instance, after a powerfail or error retry). 


Driver access: 
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Not initialized, not referenced 
Description: 


This field contains a pointer to the UCB extension in 
secondary pool for mass storage devices with DV.MSD set, 
(DV.MSD=1). 


For information on formatting, see the description of the 
UCBDF$ macro. 


U.PRM (Device-dependent words) 
Driver access: 
Not initialized, read-write. 
Description: 


The driver establishes this variable-length block of words to 


Suit device-specific requirements. For example, a disk 
driver uses the first words to store the disk geometry as 
follows: 

eBLKB 1 :># OF SECTORS PER TRACK 

eBLKB 1 °# OF TRACKS PER CYLINDER 

- BLKW 1 °# OF CYLINDERS PER VOLUME 


The driver can call the SCVLBN routine (described in Chapter 
7) to convert a logical block number to a disk address based 
on the values in U.PRM and U.PRM+2. 


4.4.5 The Status Control Block (SCB) 


Figure 4-10 is a layout of the SCB. The SCB contains the context for 
a unit operation and describes the status of a unit that can run in 
parallel with all other units. 


Figure 4-10: 
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Status Control Block 


S.LHD 


S.FRK 


S.KS5 

S.PKT 
S.CTM/S.1TM 
S.STS/S.ST3 
$.5T2 


S.KRB 


S.KTB 


Input/Output 
Queue Listhead 


Current Time-Out Count 


j KRB Address 0 | 
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@ 
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5 KRB Address n a 
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The fields* in the SCB are described as follows: 
S.LHD (first word equals zero; second word points to first) 
Driver access: 
Initialized, not referenced. 
Description: 
Two words forming the I/O queue  listhead. The first word 
points to the first I/O Packet in the queue, and the second 
word points to the last I/O Packet in the queue. If the 
queue is empty, the first word is zero, and the second word 
points to the first word. 
S.FRK (reserve four words of storage) 
Driver access: 
Initialize words to zero, not referenced. 


Description: 


The four words starting at S.FRK are used for fork-block 
storage if and when the driver deems it necessary to 
establish itself as a Fork process. Fork-block storage 
preserves the state of the driver, which is restored when the 
driver regains control at fork level. This area is 
automatically used if the driver calls SFORK. 


S.KS5 (0) 
Driver access: 
Initialized, not referenced. 
Description: 


This word contains the contents of KISAR5 necessary to 
correctly alter the Executive mapping to reach the driver for 
this unit. It is set by PROLOD, and whenever a fork block is 
dequeued and executed, this word is unconditionally jammed 
into KISAR5. ADJACENCY WITH THE FORK BLOCK IS ASSUMED! 


S.PKT (reserve one word of storage) 


* Parenthesized contents following the symbolic offset indicate the 
value to be initialized in the data base source code. | 
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Driver access: 
Not initialized, read-only. 


Description: 


Address of the current I/O Packet established by S$GTPKT. The 
Executive uses this field to retrieve the I/O Packet address 


upon the completion of an I/O request. S.PKT is not modified 
after the packet is completed. 


S.CTM (0) 
Driver access: 
Not initialized, read-write. 


Description: 


P/OS supports device timeout, which enables a driver to limit 
the time that elapses between the issuing of an I/O operation 
and its termination. The current timeout count (in seconds) 
is typically initialized by moving S.ITM (initial timeout 
count) into S.CTM. The Executive clock service (in module 
TDSCH) examines active times, decrements them, and, if they 


reach zero, calls the driver at its device timeout entry 
point. 


The internal clock count is kept in 1-second increments. 
Thus, a time count of 1 is not precise because the internal 
clocking mechanism is operating asynchronously with driver 
execution. The minimum meaningful clock interval is 2 if you 
intend to treat timeout as a consistently detectable error 


condition. If the count is zero, then no timeout occurs; a 
zero value is, in fact, an indication that timeout is not 
operative. The maximum count is 250. The driver is 
responsible for setting this field. Resetting occurs at 


actual timeout or within S$FORK and SIODON. 
S.ITM (initial timeout count) 
Driver access: 
Initialized, read-only. 
Description: 


Contains the initial timeout value that the driver can load 
into S.CTM to begin device timeout. 


S.STS (0) 
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Driver access: 
Initialized, not referenced. 
Description: 


Establishes the controller as busy/not busy (nonzero/zero). 
This byte is the interlock mechanism for marking a driver as 
busy for a specific controller. The byte is tested and set 
by S$GTPKT and reset by SIODON. 


S.ST3 (driver-specific status byte) 
Driver access: 
Initialized, referenced by driver for synchronization. 
Description: 


This status byte is reserved for driver-specific status bits 
concerning driver-executive or driver-driver communication. 
Figure 4-11 shows the layout of this byte. 


S.ST3 (S.STS) 


15 8 
Si tee eee 


S3.DRL - Reserved 

S$3.NRL - Reserved 

S3.SIP - Seek in progress on drive 

S3.ATN -— Reserved 

S3.SLV - Reserved 

S3.SPA -— Reserved 

S3.SPB - Reserved 

S3.O0PT — Seek optimization enabled (1 yes) 


Figure 4-ll: Controller Status Extension 3 


The following are the descriptions for the currently defined 
bits. All currently defined bits are used by mass storage 
devices. 
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S3.SIP=4 

If this bit is set, the drive has a seek in progress. A 
driver that supports overlapped seek operations examines this 
bit to keep track of whether the drive is seeking. For a 


driver that does not support overlapped operations, this bit 
is set to indicate that a positioning operation is in 
progress. 
S3.SPB=100 
If this bit is set, port B on this unit is spinning up. 
S3.OPT=200 
Reserved for future use. Must be clear. 
S.ST2 (controller status extension) 

Driver access: 
Initialized. 

Description: 
This status word defines certain status conditions for. the 


controller-unit combination. Figure 4-12 shows the layout of 
this word. 
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S.ST2 


15 8,7 0 
ee eee 
eee - Error in progress (1 = yes) 
$0. 106 & Resend 
S2.MAD - Multiaccess device (l = yes) 


S2.LDS - Reserved (not supported) 

S2.OPT - Device supports seek optimization (1 yes) 
S2.CON - Contiguous KRB/SCB allocation (1 yes) 
S2.OP1 - Indicates the type of optimization used 
S2.OP2 - Indicates the type of optimization used 
S2.ACT - Driver has operation (I/O) active (1 yes) 


Figure 4-12: Controller Status Extension 2 


DIGITAL has attempted to restrict bits in this word to’ those 
defining system-wide’ status. Specific bits for driver and 
Executive synchronization or driver internal synchronization 
are allocated from S.ST3. The following are the descriptions 
for the currently defined bits: 


S2.MAD=10 


This bit indicates the presence of the table of KRB addresses 
at the end of the Status Control Block. PROLOD will relocate 
these KRB addresses, but it is the drivers' responsibility to 
manage controller assignment. 


S2.CON=200 


This bit indicates the contiguous allocation CE the 
controller request and status control blocks. Devices that 
do not Support overlapped operation do not require a separate 
SCB for each unit. The KRB and SCB for such devices can be 
contiguous and some fields in the SCB overlap those in the 
KRB. Therefore, the SCB offsets S.CSR, S.PRI, S.VCT, and 
S.CON are valid only for such devices. For these devices, 
S2.CON is set. 


For the layout of the contiguous KRB and SCB, refer to 
Section 4.4.7. 


S2.ACT=2000 
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If this bit is set, the driver nas active I/O. 
S.KRB (pointer to currently assigned KRB) 


Driver access: 


Initialized, referenced by driver to access the KRB. 


Description: 


This word points to the currently assigned controller request 
block. If this word has a value of zero, then the device has 
no currently assigned KRB. It may, in fact, not have a eKRB 


or CTB at all. Both the null driver and virtual terminal 
driver have no KRB. 


Certain restrictions apply to drivers whose data bases do not 
include KRBs. They will receive powerfail, timeout, and 
cancel calls like any other driver, but the priority will 


always be zero, and the CSR address and controller index 
(where supplied) will be undefined. 


NOTE 


All code that checks S.KRB for a KRB- pointer 
must check for a possible zero value and take 
appropriate action. A zero value in S.KRB 
does not necessarily mean that a KRB does not 
exist, but perhaps rather that one is not 


currently assigned. P/OS systems do not 
currently provice active Support of 
multi-~access devices. If needed, however, 


the driver may dynamically change this KRB 
pointer for its own purposes. 


The first cell in the KRB (K.CSR) contains the control and 
device register address for the controller. 


S.KTB (KRB addresses) 
Driver access: 
Initialized. 
Description: 


This table appears only if and the device is multiaccess (the 
S2.MAD bit set). 
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Every controller to which the unit (unit control block = and 
status Control block combination) can communicate is 
represented in this table by a controller request block 
address. The table contains at least two entries, with the 
list terminated by a zero word. Only the driver may change 
S.KRB, and it may or may not use the low-order bit of the KRB 
addresses in S.KRB as an on-line and off-line flag. System 
software (other than the driver) must not modify S.KRB and 
must tolerate a lin the low-order bit of the values in 
OeKIB. 


4.4.6 The Controller Request Block (KRB) 


Figure 4-13 is a layout of the controller request’ block. One KRB 
exists for each controller. If a controller allows only a single 
operation on a single unit at a time, then the driver can allocate the 
controller request block and the status control block in contiguous 
Space. With such contiguous allocation, all offsets commonly used by 
the driver are referenced by their S.xxx forms. The system will still 
use the offset S.KRB and the K.xxx forms for all references. Refer to 
Section 4.4.7 for the contiguous SCB/KRB allocation. 
The fields* in the KRB are described as follows: 
K.PRM (device-dependent storage) 

Driver access: 

Initialized, read-write. 


Description: 


PROLOD does not relocate any addresses in this area. 


* Parenthesized comments following the symbolic offset indicate the 
value to be initialized in the data base source code. 
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Figure 4-13: Controller Request Block 


K.ICSR 
K.SLT 


K:PRM 

K.VCT5/ K.PRIP 
K.1OC/K.CON> 
K.STS 

K.CSR> 

K.OFF 

K.HPU 

K.OWN 


K.CRQ ! 


K.URM 12 


Start of UCB table 


interrupt controller CSR 


Driver dependent storage 


Controller request queue listhead 


UCB address physical unit n 


10 


14 
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K.PRI (device priority) 
Driver access: 
Initialized, read-only. 
Description: 


Contains the priority at which the device interrupts. Use 
symbolic values (for example, PR4) to initialize this field 
in the driver data source code. These symbolic values are 
defined by issuing the HWDDFS macro. 
K.VCT (interrupt vector divided by 4) 
Driver access: 
TInitialized, not referenced. 
Description: 
First interrupt vector address divided by 4. 
K.CON (controller number times 2) 
Driver access: 
Initialized, read-only. 


Description: 


Controller number multiplied by 2. Drivers that support more 
than one controller use this field. A driver may use K.CON 
to index into a controller table created in the driver data 
base source code and maintained internally by the driver 
itself. By indexing the controller table, the driver can 
service the correct controller when a device interrupts. 


Because this number is an index into the table of addresses 
in the CTB, its maximum value is limited by the value of 
Le»NUM in that CTB. 
K.I0oc (0) 
Driver access: 


Initialized, not referenced. 


Description: 


A 
ra 
a 
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Reserved for future use. 


K.STS (controller-specific status) 


Driver access: 


Initialized, not referenced. 


Description: 


This word is used as a status word that concerns’ the 


controller. Figure 4-14 shows the layout of the controller 
status word. 


K.STS ewes) 


PT td dt tp pp dP pp db dbp Unused bits are reserved 
for system use and expansion. 


KS.OFL - Controller offline 

KS.MOF - Controller marked for offline 
KS.UOP - Supports overlapped operation 
KS.MBC — Reserved 

KS.SDX - Seeks allowed during data transfers 
KS.POE - Parallel operation enabled 

KS.UCB - UCB table present 

KS.DIP - Data transfer in progress 

KS.PDF - Privileged diagnostic functions only 
KS.EXT - Extended 22-bit UNIBUS controller 
KS.SLO - Controller is slow coming online 


Figure 4-14: Controller Status Word 


All undefined bits are reserved for use by DIGITAL. 
Currently defined bits are: 


KS .MOF=2 


If this bit is set, the unit/controller is in the process of 
becoming offline. 


KS .UOP=4 
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This bit indicates whether the controller supports unit 
Operation in parallel and requires synchronization. If this 
bit is set, each unit attached to the controller is capable 
of operating independently. Therefore, the KRB contains a 
UCB table holding the UCB addresses of each independent unit. 


KS .SDX=20 


If this bit is set, the controller allows seek operations to 
be initiated while a data transfer is in progress. (Some 
types of disks, such as the RKO0O6 and RKO7, support overlapped 
seek operations but do not allow a seek to be initiated if a 
data transfer is in progress.) The Executive routines Request 
Controller for Control Function (SROCNC) and Request 
Controller for Data Transfer (SROCND) examine this bit to 
distinguish between the two types of controllers that support 
overlapped seeks. 


KS .POE=40 


If this bit is set, the driver may initiate an I/O operation 
on the controller in parallel with other I/O operations. A 
driver that supports overlapped seek operations checks’ this 
bit to decide whether it should attempt to perform an I/O 
operation as a seek phase and then a data transfer phase 
(that is, overlapped) or as an implied seek (that is, 
nonoverlapped). If this bit is set, the driver can then 
attempt the overlapped operation. 


An overlapped driver must check this bit once only for _ each 
I/O operation. The driver must not rely on the bit value to 
decide whether, upon being interrupted, the driver was 
attempting a seek operation. The driver should use the 
S2.SIP bit to hold its internal state. 


KS .UCB=100 


This bit indicates the presence of the table of unit control 
block addresses associated with the KRB. If this bit is set, 
K.OFF gives the offset from the beginning of the KRB to the 
start of the UCB table. 


Devices that support unit operation in parallel (for example, 
overlapped seeks) require a mechanism for finding the UCB of 
the unit generating an interrupt. Therefore, if KS.UOP is 
set, a UCB table must exist. If KS.UOP is not set, however, 
a UCB table may still exist because some devices (for 
example, terminal multiplexers) support full unit operation 
in parallel but do not require synchronization. Therefore, 
KS.UCB may be used to determine whether the UCB table exists, 
regardless of whether KS.UOP is set. 
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KS.DIP=200 


If this bit is set, a data transfer is in progress. A driver 
that supports overlapped seek operation sets or clears this 
bit to indicate to itself whether, after an interrupt, a data 
transfer is in progress. The driver must set or clear this 
bit. Usage of this bit eliminates the need for the software 
to access the device registers to determine what type of 
Operation was in progress. 


K.CSR (start of controller device register addresses) 
Driver access: 
Initialized, read-only. 
Description: 


Contains the first address of the device for the device 


controller. The driver uses K.CSR to initiate I/0 
operations. 


NOTE 


This word is guaranteed to be offset zero for 
the KRB. 


K.OFF (offset in bytes (from K.CSR) to start of UCB table) 


Driver access: 


Initialized, referenced by interrupt dispatch code. 


Description: 


This word contains the offset to the beginning of the unit 
control block table. When added to the starting address of 
the KRB, it yields the UCB table address. 


The status bit KS.UCB may be used to determine whether the 
UCB table exists. A UCB table may exist if KS.UOP is not 
set, since some devices (for example, terminal multiplexers) 
support full unit operation in parallel with no 
synchronization required. If KS.UOP is set, a UCB table must 
appear (and KS.UCB will also be set). 


K.HPU (highest physical unit number) 


Driver access: 


DRIVER DATA STRUCTURE DETAILS 


Initialized. 


Description: 


This byte contains the value of the highest physical unit 
number used on this controller. 


K.OWN (0) 


Driver access: 


Initialized, referenced for actual unit. 


Description: 


This word has three slightly different uses, depending on the 
particular device. 


1. 


For controllers which always have only aeesingle unit 
connected to them (for example, the line printer), 
K.OWN/S.OWN always points to the UCB of that unit. You 
can use the suc argument in the GTPKTS macro to 
statically initialize this cell in the data base. 


For controllers that may have multiple units attached but 
do not support unit operation in parallel, K.OWN/S.OWN is 
set with the currently active unit by code generated with 
the GTPKTS macro suc argument set to blank. 


For controllers that support unit operation in parallel 
and require synchronization (KS.UOP is set), this is a 
busy/nonbusy interlock for the controller. If the 
controller is busy for a data transfer, this’ word 
contains the UCB address of the currently active unit. 
This word is set and cleared by the Request Controller 
for Control Access (SROCNC), Request Controller for Data 
Access (SROCND), and Release Controller (S$RLCN) routines. 


K.CRO (first word equals 0; second word points to first) 


Driver access: 


Initialized, not referenced. 


Description: 


Two words that form the controller wait queue. Fork 
blocks are queued here for driver processes that have 
requested controller access. Driver processes that 


request access for control functions are queued on the 
Front of the list, and those that request access for data 
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transfer are queued on the end of the list. 


KE.UCB 
Driver access: 


Initialized, referenced by interrupt dispatch code. 


Description: 


This table contains the unit control block addresses’ for 
the units on this controller. Physical unit zero is in 
the first word, unit one is in the second word, and unit 
n iS in word n+l. The table has a length of (K.HPU+t1) 
words. A value of zero in this table indicates a 
physical unit number’ for which no actual physical unit 
exists. The table is terminated by a -l. 


NOTE 


This table exists only for those devices’ that 
have KS.UCB set. 


4.4.7 Contiguous Allocation of the SCB and KRB 


In a configuration where a controller and the Executive supports only 
a single operation on aeunit at one time, the driver can allocate 
Space for the KRB and the SCB in a contiguous area. Some fields of 
the KRB overlap those in the SCB. Although the KRB and SCB in this 
arrangement are contiguous, the system still considers the I/O data 
Structure to contain a KRB. The system will still use the S.KRB 
offset and the K.xxx forms for all references. The driver can 
reference the fields by the S.xxx form of the symbolic offset 
definitions. Figure 4-15 shows the physical layout of the contiguous 
KRB and SCB allocation. 


4.4.8 Controller Table (CTB) 


Figure 4-16 is a layout of the controller table. You ensure that’ the 
CTB is linked into the system list of controller tables by placing the 
CTB macro immediately before the allocation of the L.LNK word. The 
CTB macro generates a global symbol that links the user-written CTB 
into the system list. 
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Figure 4-15: Contiguous KRB/SCB Allocation 


K.ICSR interrupt controller CSR 
K.PRM Driver-dependent storage 
S.VCT/S.PRI K.VCT/K.PRI Vector/4 Priority 


S.CON K.1IO0C/K.CON Controller |/O Count Controller index 


K.STS Controller status 


S.CSR K.CSR Pointer to CSR 


K.OFF Offset to UCB table 
K.HPU Unused 


Highest physical unit 
K.OWN Owner UCB 


S.LHD K.CRO Input/output queue listhead 


S.FRK Fork Link 
Fork PC 
Fork R5 
Fork R4 


S.KS5 KISAR5 
S.PKT |/O packet address 


S.CTM/S.ITM Initial Time-Out Count | Current Time-Out Count 


Status 


S.STS/S.ST3 Status Extension 
S.ST2 Status extension 


S.KRB KRB address 


KE.RHB 
Start of UCB table 


UCB address physical unit 0 


UCB address physical unit n 
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L.CLK ei i ea ] 


KRB address n 


' The head of the list of controller tables is $CTLST in SYSCM. 
If LS.CIN is set, this cell points to the common interrupt 
address table rather than to the DCB. 


Figure 4-16: Controller Table 


The fields* in the CTB are described below: 
L.CLK 
Driver access: 
Initialized 
Description: 


This is the clock queue entry for these devices that need a 


* Parenthesized contents following the symbolic offset indicate the 
value to be initialized in the data base source code. 


4-63 


DRIVER DATA STRUCTURE DETAILS 
Single clock block per generic controller type. It only 
appears if LS.CLK is set. 
L.ICB (reserve one word of storage) 
Driver access: 


Not initialized, not referenced. 


Description: 


This word points to the first interrupt control block for 
this type of controller. | 


LeLNK (0 or link to next CTB in list) 
Driver access: 
Not initialized, not referenced. 


Description: 


All of the controller tables in the system are linked 


together so they can be found, and they are threaded through 
this first word. A zero link terminates this list. 


A CTB must exist for every physical controller type in the 
system. 


LeDID (controller's hardware ID) 
Driver access: 
Initialized, read-only. 


Description: 


This hardware ID is the controller mnemonic used to find this 
controller table from among all the others in the system. 


Le-NUM (number of KRB addresses) 
Driver access: 
Initialized, read only. 


Description: 


DRIVER DATA STRUCTURE DETAILS 


Used by programs that scan the controller tables to compute 
the number of KRB addresses. This value is never zero, since 
without controller request blocks there’ should be no 
controller table. 
L.STS (generic controller status) 
Driver access: 


Initialized, read only. 


Description: 


The controller table status bits give information about’ the 


class of controllers. Figure 4-17 shows the layout of this 
byte. 


L.STS L.NUM (1 = yes) 


15 8 
PET TEE PF tr system use and exp 
ili | for system use and expansion. 


LS.CLK - Clock block allocated 

LS.MDC - Multidriver controller 

LS.CBL - Clock block linked into clock queue 

LS.CIN - Controller uses common interrupt address table 
LS.NET - DECnet device 


Figure 4-17: Controller Table Status Byte 


The following are the descriptions of these bits: 


LS .CLK=1 


If this bit is set, the controller table has an 8-word clock 
block. 


LS .MDC=2 


If this bit is set, multiple drivers service units attached 
to the associated controller. 


LS .CBL=4 
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If this bit is set, the clock block is linked into the clock 
queue. 


L.KRB (KRB addresses of controllers) 
Driver access: 
Initialized once for the controller, not referenced. 
Description: 


A list of the controller request block addresses ordered by 
their respective controller numbers. This table is indexed 
by the controller index retrieved from the PS word 
immediately after an interrupt. The table is of length 
(L.NUM) words. While the interrupt routines will not have to 
scan the list in a linear fashion, the only way to find all 
the controller request blocks in the system includes a linear 
scan of all the controller tables. The CTB is static. 


The address of the start of the KRB address list in the CTB 
is the global symbol SxxCTB in the driver dispatch table. 
PROLOD supplies this address in the DDT when it loads’ the 
driver. 


Proper action for drivers to access their list of KRB 
addresses is to retrieve the address of the start of the KRB 
list in the CTB from the cell in the driver dispatch table 
set up by PROLOD. 


4.5 DRIVER CODE DETAILS 


This section describes the specific requirements for driver code. The 
driver code must contain a driver dispatch table which allows the 
Executive to call the driver to perform discrete system functions. If 
the driver needs to access either system structures such as the 
partition and task control blocks or structures within its own data 
base, it should use the system-wide symbolic offsets rather than the 
real offsets. Because the driver is built with the Executive library 
EXELIB.OLB, the symbolic offsets are automatically defined for the 
driver code. If you want to see the definitions of the symbols in 
your driver listing, place in your driver source code the related 
macro name ina .MCALL directive and invoke the macro. (For your 
convenience, the source code of the macro calls that define the 
symbols of structures is in Appendix A.) The detailed descriptions of 
the driver data base structures are in Section 4.4. 
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4.5.1 Driver Dispatch Table Format 


The driver dispatch table associates the entry points that the 
Executive expects to find in a device driver and the actual locations 
of the routines in the driver code. The DDT also provides a link from 
the driver code to the driver data base. Figure 4-18 shows the format 
of the DDT. Section 4.3.1 describes the DDTS macro call, which 
automatically generates the DDT. 


All device drivers require a driver dispatch table somewhere in the 
first 4K words of the driver code. Conventionally, the table is 
located at the beginning of the code. 


NOTE 


If the length of a driver must exceed 4K words (20000 
octal bytes), then your driver must set up the mapping 
for the second 4K words whenever it is entered; and, 
of course, all entry points must be in the first 4K 
words of the driver. 


The driver must define some labels that the Executive routines and the 
INTSVS macro call use to access the DDT. Table 4-10 lists these 
labels, which are automatically generated by the DDTS macro call. 
Because these labels do not appear in the DDT itself, their format is 
fixed and they must be specified in the format shown. 


Table 4-9: Labels Required for the Driver Dispatch Table 


Required Format Meaning 


SxxTBL:: Defines the start of the DDT. The PROLOD 
routines use this label to fill in D.DSP. 


XXCTB: Defines the pointer to the table of KRB 
addresses in the CTB of the controller for 
device xx. Because a driver can _ support 
different types of controllers, there may 
be more than one of this form of label. 
(The DDTS macro Supports only one 
controller type.) 


SxxTBE:: Defines the end of the DDT for Executive 
PROLOD and PROUNL routines that scan the 
DDT. 
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RE re ey) Rare Ne a rr 


Next Command/Optimization Entry Point Address 


Ra 


D.VNXC, D.VCHK'! 


D.VDEB' Deallocation Entry Point Address 


Generic Controller Name (ASCII) for xy 


Interrupt Entry Point Address 0 


Interrupt Entry Point Address' 


Pointer to KRB table in CTB (for INTSV$) for xy controller 
Pointer to KRB Table in CTB (for INTSV$) for wz controller 


{wore 


wzCTB: 


1. These are optional advance driver features 


Figure 4-18: Driver Dispatch Table Format 


At offsets D.VINI through D.VUCB in the DDT of your 
labels defining the addresses of the entry points in the driver. 
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standard procedure, you supply the labels described in Table 4-10 at 
the entry points in the driver code. The formats of the standard 
labels that appear in the DDT are not fixed. Because the Executive 
expects to find the entry point addresses at fixed offsets from the 
start of the DDT and the labels themselves appear in the DDT, you can 
change their format if you construct the DDT without using the DDTS 
macro call. (However, other labels that are required in the driver 
code but do not appear in the DDT have a certain, fixed format which 
you must not change. For reference, these fixed format labels are: 


SxxTBL:: 
XXCTBs 

SxxTBE:: 
SxxLOAs: : 
SxxUNL:: 
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These fixed-format labels are described elsewhere in this’ chapter.) 
The DDTS macro uses the standard labels but allows you to alter the 
format of some of them. 


At offset D.VINT in the DDT is the name of the controller type that 
the driver supports. (The same name is in the CTB.) If the driver has 
no controller (such as the virtual terminal driver VTDRV), this word 
is zero. The structure allows the driver to support multiple 
controller types. (The terminal driver supports different controller 
types.) Although the DDTS macro Supports only one controller type, 
there 1s no restriction on the number of controller types that a 
driver can support. 


After each controller name follows a block of interrupt entry 
addresses. At location D.VINT+2 begins the first interrupt address 
block, each word of which defines an address to be included in a 
vector for the driver. A zero terminates the block and indicates that 
there are no more interrupt entry points for the controller. There is 
no restriction on the number of vectors each controller may have. For 
a Single interrupt device, location D.VINT+2 (interrupt entry address 
0) is the interrupt address. 


Table 4-10: Standard Labels for Driver Entry Points 


Label Entry Point 


xxINI: I/O initiation 

xxCAN: Cancel I/O 

xxCHK : Block check and conversion 
XxOUT: Device timeout 

XXPWF : Power failure 

XXKRB:; Controller status change 
XxUCB: Unit status change 
SxXxINT::3 Interrupt entry point 


* The characters xx are the 2-character mnemonic. 
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Figure 4-19: Sample Interrupt Address Block in the DDT 


4.5.2 I/0 Initiation Entry Point 


The offset D.VINI in the driver dispatch table contains the address of 
this entry point. A driver is called at this entry point at priority 
O from the Executive routine S$DRORO in the module DRQIO. A driver 
should call the Executive SGTPKT routine to get an I/O packet to 
process. This action dequeues an I/O request. The following are the 
register conventions when the Executive enters the driver. 


R5 = address of the UCB of the unit for which the Executive has 
queued an I/O packet 


This entry condition pertains unless the driver wants to delay the 
queuing operation. Therefore, if the queue-to-driver bit UC.QUE in 
the unit status block offset U.CTL is set, the following are_ the 
register conventions. 


R5 = UCB address of unit for which a packet has been created 
R4 = SCB address of the related unit 
Rl = address of the I/O packet 


You may find more information on and coding requirements for the hone 
queue-to-driver operation in the description of the UC.QUE bit in 
Section 4.4.4 and an example of its use in Chapter 8. 
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The GTPKTS macro call automatically generates the call to the SGTPKT 
routine and the code to process the return from SGTPKT. Upon return 
from SGTPKT, the C bit indicates whether there is a packet to process. 


c= 1 If the C bit is set, the Executive found the controller 
busy, could not dequeue a request, or had to call SFORK 
to have the driver run on the correct processor. 


C = 0 If the C bit is clear, the Executive successfully 
dequeued a packet for the driver and placed it in the 
device's input/output queue. 


If a request was successfully dequeued, the following are the contents 
of the registers: 


R5 = Address of unit control block 

R4 Address of status control block 

R3 = Controller index 

Physical unit number of device to process 
Address of the I/O packet 


A 
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If the C bit is set, the driver returns control to the caller (a 
RETURN instruction should be executed). If the C bit is clear, the 
generated code loads the location at offset K.OWN/S.OWN in the 
contiguous KRB/SCB with the UCB address of the unit to process. The 
driver may then process the request and activate the device. All 
registers are available to the driver. The driver executes a RETURN 
instruction to transfer control to the system. 


4.5.3 Cancel Entry Point 


The offset D.VCAN in the driver dispatch table contains the address of 
this entry point. The Executive routine SIOKIL in the IOSUB module 
calls the driver at this entry point at device priority. When the 
Executive enters the driver, the following register conventions 
pertain: 


R5 = UCB address 
R4 = SCB address 
R3 = Controller index (undefined if S.KRB equals zero) 


Rl = Address of TCB of current task 
RO = Address of active I/O packet 
The usage of this entry point is explained in Section 2.2.2. All 


registers are available to the driver. The driver returns control to 
the Executive by executing a RETURN instruction. 
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4.5.4 Device Timeout Entry Point 


The offset D.VTIM in the driver dispatch table contains the address of 
this entry point. Routines in the Executive module TDSCH call the 
driver at this entry point at device priority. When the Executive 
enters the driver, the entry conditions are as follows: 


R5 = UCB address 
R4 = SCB address 
R3 = Controller index (undefined if S.KRB equals zero) 
R2 = Address of device CSR 
RO = I/O status code IE.DNR (Device Not Ready) 
The usage of this entry point is explained in Section 2.2.3. All 


registers are available to the driver. The driver returns control to 
the Executive by executing a RETURN instruction. 


4.5.5 Deallocation Entry Point 


The offset D.VDEB in the driver dispatch table contains the address of 


this entry point. This entry point is called at priority zero from 
the routine SFINBF in the Executive module SYSXT after a buffered I/0 
request completes. The driver is expected to deallocate its buffers 
at this entry point. When called, the registers are set up as 
follows: 


RO = address of the first buffer 


All registers are available to the driver. The driver returns control 
to the Executive by executing a RETURN instruction. 


4.5.6 Power Failure Entry Point 


The offset D.VPWF in the driver dispatch table contains the address of 
this entry point. The routines in the Executive module POWER call the 
driver at this entry point at priority 0 for both unit and controller 
power failures. The Executive first calls the driver for controller 
power failure with the C bit set. The driver is called in this 
fashion once for each controller. The following are the register 
conventions: 


C bit set (controller power failure) 


R3 
R2 


CTB address 
KRB address 


The driver may use all registers. 
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After the Executive has called the driver for all related controllers, 
it calls the driver once for each unit power failure at priority 0 
with the C bit clear. The following are the register conventions: 


C bit clear (unit power failure) 


R5 = UCB address 
R4 = SCB address 
R3 = Controller index 


For both controller and unit power failures, the driver returns 
control to the calling routine by executing a RETURN instruction. 


4.5.7 Controller Status Change Entry Point 


The offset D.VKRB in the driver dispatch table contains the address of 
this entry point. The Executive routine SKRBSC in the OLRSR module 
calls the driver at this entry point at priority 0 to put a controller 
on-line or to take a controller off-line. 

The C bit indicates whether the request is for off-line or on-line. 
The following are the register conventions upon entry to the driver. 


R3 = CTB address for the controller 

R2 = KRB address of controller changing status 

= Return address for completion 

2(SP) = Return address for caller of the Executive routine 


The C bit is set to indicate the requested status change as follows: 


C = 1 On-line to off-line transition 
0 Off-line to on-line transition 


oe) 
1 


The status change byte SSCERR is preset as follows: 
SSCERR = 1 
The driver indicates the return status in the S$SCERR byte as follows: 


SSCERR < 0 Operation is not successful and a negative value in 
SSCERR is the I/O error code. Thus, a negative value 
rejects the status change requested by the C bit. 


SSCERR = 1 Operation is’ successful. The driver accepts’ the 
status change requested. This is the default 
condition. 


All registers are available to the driver. The Executive does not 


change the status of the controller until and unless the driver shows 
successful completion of the on-line or off-line request. 
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The driver must return immediately by either of the following methods: 


1. The driver can indicate the return status immediately and can 
return to the first address on the stack in the normal 
fashion. If the driver accepts the status change, it merely 
executes a RETURN instruction. (The status change byte 
SSCERR has been preset with 1.) If the driver rejects the 
status change, it loads the relevant I/O error code into 
SSCERR and executes a RETURN instruction. 


2. The driver need not indicate the status immediately but 
removes the first address from the stack, saves it, and 
returns immediately to the second address. The driver then 
has 60 seconds to perform its processing, to indicate the 
return status, and to return to the first address. The 
driver can use the offset S.CTM in the status control block 
to time out some operation (such as a protocol rundown) = and 
then accept or reject the operation by using $SCERR. 


If the driver does not return to the first address on the stack, the 
system can be considered to be in an indeterminate state and possibly 
corrupted. The driver must return immediately because status changes 
should not stall the system. The 60-Second delay allows a driver time 
to overcome conditions over which it has little control (such as 


network connections). System disk and terminal drivers must indicate 
return status immediately. 


4.5.8 Unit Status Change Entry Point 


The offset D.VUCB in the driver dispatch table contains the address of 
this entry point. The Executive routine SUCBSC in the OLRSR module 
calls the driver at this entry point at priority 0O to put aeunit 
On-line or to take a iunit off-line. This entry is called once for 
each unit whose status changes. The C bit indicates whether’ the 


request is for on-line or off-line. The following are the register 
conventions: 


R5 = Address of UCB or unit changing status 

R4 = Address of SCB of unit 

R3 = Controller index (undefined if S.KRB equals zero) 
O0(SP) = Return address for driver completion 
2(SP) = Return address for caller of the Executive routine 


The C bit is set to indicate the requested status change as follows: 


C = 1 On-line to off-line transition 
= 0 Off-line to on-line transition 
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The status change byte SSCERR is preset as follows: 
SSCERR = 1 
The driver indicates the return status in the $SCERR byte as follows: 


SSCERR < 0 Operation is not successful and a negative value in 
SSCERR is the I/O error code. Thus, a negative value 
rejects the change requested by the C bit. 


SSCERR = 1 Operation is successful. The driver accepts’ the 
status change requested. This is the default 
condition. | 


All registers are available to the driver. The driver must return 
within 60 seconds. The Executive does not change the status of a unit 
until and unless the driver shows successful completion of the on-line 
or off-line request. 


The driver must return immediately by either of the following methods: 


1. The driver can indicate the return status immediately and can 
return to the first address on the stack in the normal 
fashion. If the driver accepts the status change, it merely 
executes a RETURN instruction. (The status change byte 
SSCERR has been preset with 1.) If the driver rejects’ the 
Status change, it loads the relevant I/O error code into 
SSCERR and executes a RETURN instruction. | 


2. The driver need not indicate the status immediately but. 
removes the first address from the stack, saves it, and 
returns immediately to the second address. The driver’ then 
has 60 seconds to perform its processing, to indicate the 
return status, and to return to the first address. The 
driver can use the offset S.CTM in the status control block 
to time out some operation (such as a protocol rundown) = and 
then accept or reject the operation by using SSCERR. 


If the driver does not return to the first address on the stack, the 
system can be considered to be in an indeterminate state and possibly 
corrupted. The driver must return immediately because status changes 
should not stall the system. The 60-second delay allows a driver time 
to overcome conditions over which it has little control (Such as 
network connections). System disk and terminal drivers must indicate 
return status immediately. 


4.5.9 Interrupt Entry Point 


Upon an interrupt, control is dispatched to the driver from an 
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interrupt vector through an interrupt control block or directly from 
an interrupt vector. A device may have more than one interrupt entry 
point. The entries in the DDT interrupt address block are used to 
initialize either the vector(s) or the interrupt control block with 
the address(es) of the related interrupt entry point(s). (Refer to 
Section 4.5.1 for a discussion of the interrupt address’ block.) All 
drivers should observe the protocol for handling interrupts introduced 
in Section 1.3 and summarized in Section 4.1. 


The driver will be called from the interrupt dispatch coroutine SINTSI 
in the Executive. The following are the register contents when the 
driver gets control: 


R4 = Controller index 


Registers R4 and R5 are available to the driver. The driver runs at 
the priority set in the interrupt control block. To dismiss the 
interrupt, a driver executes a RETURN instruction. 


Drivers should use the INTSVS$S macro call at an interrupt entry point, 
in order to resolve entry processing. INTSVS does not generate a call 
to SINTSV because PROLOD establishes in the interrupt control block 
the call to the SINTSI coroutine. The SINTSI coroutine saves R4 and 
R5; sets the priority to that in the interrupt control block; and 
forms the controller index from the PS and stores it in R4. 


INTSVS generates code to load RS5 with the UCB address of the 
interrupting unit. After the INTSV$ call in the driver code, the 
following conditions apply: 


R5 = UCB address of the interrupting unit 
R4 Controller index 


The driver may then do the following: 
1. Save extra registers if necessary 
2. Do whatever processing is necessary 


3. Become a fork process to access the data structures or to 
call Executive routines if necessary 


4, Restore the explicitly saved extra registers 


5. Execute a RETURN instruction to the coroutine, which 
dismisses the interrupt 


DRIVER CODE DETAILS 


4.5.10 Volume Valid Processing 


System-Supplied drivers that service mountable devices (those that 
have the DV.MNT bit in the UCB U.CWl word set) take advantage of 
special processing of volume valid for a device. For such devices the 
Executive directive processor DROQIO checks that either of the mounted 
Status bits US.MNT or US.FOR in the UCB U.STS word is set. If a 
mounted status bit is not set, DROQIO requires that a device-specific 
bit called volume valid (US.VV) be set or else it rejects’ the 
directive. If a mounted status bit is set, DROIO does not check the 
volume valid bit. (DROIO assumes that the MOUNT command properly set 
the volume valid bit.) 


To effectively service a mountable device on the system, a 
user-written driver should perform in one of two ways. First, it can 
take advantage of the volume valid capability in the same way that a 
system-supplied driver does. This processing involves calling the 
SVOLVD routine in the Executive module IOSUB, and handling the 
spinning-up status bit (US.SPU) and the volume valid bit (US.VV) in 
the UCB status byte U.STS. (For details of this mechanism, refer to 
driver source code supplied on the system.) Second, a user-written 
driver can circumvent the volume valid processing by doing’ the 
following: 


1. Enable the set characteristics function (IO.STC) for volume 
valid in the DCB legal function mask word 


2. Enable the same function in the DCB no-op function mask work 


3. Statically set the US.VV bit in the UCB in the driver data 
base source code 


The second method allows the device to be successfully mounted and 
associated with an ancillary control processor without your having to 
include code in the driver to handle US.VV. 


CHAPTER 5 


INCORPORATING A USER-SUPPLIED DRIVER INTO P/OS 


This chapter describes how to incorporate a user-supplied driver into 
an P/OS' system. The material in the chapter depends on your having 


created source code according to the programming specifics given in 
Chapter 4. 


5.1 INCORPORATING AN I/O DRIVER INTO A P/OS SYSTEM 


With the exception of DIGITAL supplied disk I/O drivers and the 
terminal driver, all  P/OS I/O drivers are loadable with a loadable 
database and are incorporated directly into a running system via a 
call to the PROLOD (POSSUM) system service. The driver may also be 
unloaded at runtime, as a result of a specific unload request’ to 
PROLOD. The driver database iS never removed as there are many 
structures in the system which reference the UCB. Even if it were 
possible to track down all references, the required structures might 
not be memory resident. Since the system image is not modified as a 
result of loading a new driver, the database can be removed from the 
system by rebooting P/OS. 


5.1.1 Guidelines for Creating/Adding a Driver Into the System 


To incorporate a loadable driver with a loadable database, use _ the 
following procedure: 


1. Create the driver's macro source code file and the database 
source code file in the directory of your choice. 


2. Assemble the driver and database using the prefix file 
RSXMC.MAC and the executive data structures macro library 
EXEMC.MLB. RSXMC contains the various system configuration 
symbols used by the executive's conditionalization and 
commonly used macros, such as DDTS, GTPKTS$, and INTSVS. 
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3. Taskbuild (using PAB) your driver code and database. Ensure 
that a symbol table file (.STB) is generated at this time, 
Since it is required by the PROLOD system. service. The 


symbol table file is expected to be located in the same. 
directory and have the same file name as the driver image 
file: AwikSk) « The only difference will be the file name 
extension. 


4. Create a program that will issue the PROLOD system _ service 
call to load your driver. As an aid to debugging, the 
logical "PROLODSMSG" (without the quotes) may be created 
using the DCL "ASSIGN" command and set to ASCII "0". This 
logical'’s existence will enable PROLOD ASCII error messages 
to be sent to the debugging terminal (TT2:). 


5.1.2 Assembling the I/O Driver 


After you have created the driver source code and database files, they 
must be assembled by the P/OS macro assembler (PMA). It is suggested 
that listing files be created in the event debugging is’ needed. The 
following commands illustrate this: 


PMA>DRVCOD , DRVCOD= [1,5] EXEMC/ML,RSXMC/PA:1,[]DRVCOD 
*- Assemble the driver code. 

PMA>DRVTAB , DRVTAB= [1,5] EXEMC/ML,RSXMC/PA:1,[] DRVTAB 
« Assemble the driver database. 


Note that it is not possible to use ODT in a driver since a driver is 
not a task, and it is not possible to issue a system directive from 
system state. For debugging tips and procedures, see Chapter 6. 


5.1.3 Taskbuilding the I/O Driver 


After completing the assemblies with no detected errors, taskbuild the 
driver code and database with the following commands: 


PAB>DRIVER/-HD/-MM , DRIVER,DRIVER= ? 

1) The /-HD switch is specified since a task header is not 
needed. The driver is not a task but rather an 
extension to the executive. 

2) The switch /-MM must be used in the command line. 

3) A map file is produced and is useful for debugging. 

4) A symbol table file is specified since it will be 
required by PROLOD. 
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PAB>DRVCOD 
PAB>DRVTAB 
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; 5) PAB reprompts for input files. Both the code and the 
; database are specified. The driver database is built 
; into the image following the driver code. 
PAB>[1,5]POS.STB/SS 
PAB> [1,5] EXELIB/LB 
PAB> / 
; 6) POS.STB is specified as input so that executive routine an 
; listhead references may be resolved. 
; 7) EXELIB is specified so that data structure offsets, mask, 
; and bit references may be resolved. 
; 8) The single slash begins the option phase of the task build 
Enter options: 
TKB>STACK=0 


; 9) The taskbuilder is directed not to allocate stack space. A 
: driver uses the executive's stack sparingly. 
PAB>PAR=GEN :120000: 40000 
PAB>// 
10)A partition, base virtual address and maximum size are 


specified and the double slash terminates taskbuilder 
input. 
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5.1.4 Loading an I/O Driver Into the System 


After completing the taskbuilding of your driver without any detected 
errors, you must create a small task to issue the POSSUM "PROLOD" 
system service call. If you are in the process of debugging the 
driver, it is suggested that you attach a debugging terminal to the 
printer port (TT2:), define the logical name "PROLODSMSG", and run XDT 
prior to invoking PROLOD. 


5.2 PROLOD 


The callable PROLOD system routine provides a method to load or unload 
an I/O driver into P/OS. PROLOD is an entry point in the system 
resident POSSUM library which calls the server task SLOAD. (See the 
P/OS System Reference Manual for a general description of POSSUM 
system services.) 


By default, when loading a driver, PROLOD will attempt to offline any 
competing access for the hardware option(s) that will be used by the 
driver being loaded. This is done via a controller offline request to 
the competing driver En most cases (an exeption being the 
communications driver XK:, which is handled somewhat differently). If 
the driver relinquishes control, the new driver can be successfully 
loaded. Optionally, a driver can be explicitly unloaded and removed 
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from memory if all controllers and units are successfully marked 
offline. 


To avoid memory fragmentation, PROLOD will load the driver in the 
highest available physical memory, checkpointing any eligible regions 
that may be resident in high memory. 


A user-written driver on version 2.0 P/OS systems may gain access to 
the communications port or to any hardware option modules not used by 
P/OS directly. 


PROLOD requires that both the driver image (.TSK) and the driver 
symbol table (.STB) be located on the same device and directory. The 
filename extension is assumed by PROLOD and should not be specified in 
the request. If a version number is specified, both the symbol table 
and the image must have identical version numbers (filename.;n). LE 
the version number is not specified, the highest version of each will 
be used. Unload operations currently have a restriction that requires 
access to the image and symbol table files so that PROLOD can easily 
determine which units and controllers need to be placed offline prior 
to unloading the driver code from memory. The driver's database is 
never removed from primary pool and, if the driver is reloaded, it is 
assumed that the old database can be reused. Optionally, a driver can 
specify the SLOA and SUNL entry points so that it can save, restore, 
or initialize any required context. 


To load or unload a driver, invoke PROLOD with the following 
arguments: 


STATUS , REQUEST,F ILENAME,FILENAME SIZE 


where: 

STATUS The address of the 8-word Status Block 

REQUEST The address of a word containing the value of the 
Operation to be performed. The decimal values are: 
1 = load a driver 
2 = unload a driver 

FILENAME SIZE The address of a word containing an ASCII file 
specification of the driver image and symbol file. Do 
not specify file extensions as they are assumed to be 
-TSK and .STB respectively by PROLOD. 

FILE SIZE The address of a value containing the number of 


characters in FILENAME. 
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5.3 PROLOD PROCESSING 


The PROLOD routines extensively check the driver data base. The 
following sections describe two aspects of PROLOD. 


5.3.1 PROLOD Operations and Diagnostic Checks 


Two modules (LDVLDB and LDVFIN) in PROLOD load a driver into memory: 
one checks the validity of and loads the data base; and the other 
finishes the operation by loading the driver. The data base is loaded 
into the system pool. The PROLOD routines relocate and validate many 
of the pointers within the data base and, in the process, validate 
Other data in the structures. The driver itself is then loaded into 
the highest available physical address space. 


To read the data base from the driver image file into the system pool, 


the global labels SDAT and SEND, defining the start and end of the 
data base, are needed. 


To check the data base, the PROLOD routines must know the starting 
address of the DCB. If the global label SDCB is not defined (that is, 
not in the symbol table file), the start of the DCB is assumed to be 
the first word of the data base. Many unuSual error conditions result 
when PROLOD assumes that the DCB is at the start of the data base and 
the DCB is elsewhere in the data base and not labelled properly. 
Thus, to avoid this type of problem, you should always define the 
start of the DCB with the global label SDCB. 


Each CTB is checked and relocated. The following offsets are both 
checked and relocated: 


L.LNK The link to the next CTB must be even. If it is 
not zero, it must point within the data base, and 
the CTB to which it points must lie within the 
data base. (Because it is highly unusual to have 
two controller types in one driver data base, this 
value is usually zero.) 


iL. DEB The address of the related DCB must be even, point 
within the data base, and the DCB to which it 
points must lie within the data base. The DCB 
address(es) in the table must be even, and the 
DCB(s) to which each address points must lie 
within the data base. 


Gs DED If non-zero, the system configuration table is 
scanned for the presence of a device with a 
matching hardware ID. If a match is found, then 
the KRB's, K.SLT, K.ICSR, K.CSR and K.VEC values 


are 
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are assigned. If L.DID is zero, then K.VEC and 
K.CSR are used to generate the appropriate ICB and 
to verify LSR presence. 


L.KRB Each pointer in the table of KRB addresses must be 
even and must point within the data base, and the 
KRB to which each cell points must lie within the 
data base. | 


The following offsets in the CTB are checked: 


L.NAM The controller name cannot duplicate other L.NAM 
entries in the loadable data base. 


L.NUM The number of controllers must be less than 17 
(decimal). 


Each KRB is checked and relocated. The following offsets in the KRB 
are both checked and relocated: 


K.OWN The pointer to the owner UCB must be even and 
point within the data base, or be zero. If it is 
nonzero, the pointer is relocated. 


K.OFF The start of the table of UCB addresses produced 
from K.OFF must be even and must point within the 
data base. The entries themselves must be even, 
point within the data base, and the UCB to which 
each cell points must lie within the data base. 


K.CROQ The listhead for the controller request queue. 

K.CRO+2 It is initialized to an empty list with the first 
word zero, and the second word pointing to the 
first, relocated. © | 


Each DCB is checked and relocated. The following offsets are _ both 
checked and relocated: 


D.LNK The link to the next DCB must be even. If it is 
nonzero, it must point within the data base, and 
the DCB to which it points must lie within the 
data base. 


D.UCB The link to the first UCB must be even and must 
point within the data base, and the UCB to which 
it points must lie within the data base. 

D.UCBL The length of the UCB must be even and nonzero. 

D.UNIT The highest unit number (increased by 1) used with 
D.UCBL forms the last address of all UCBs. This 
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address must lie within the data base. 


The pointer to the driver dispatch table (D.DSP) is set to zero to 
show that the driver is not yet loaded. 


Each UCB is checked and relocated. The following offsets are both 
checked and relocated: 


U.DCB The pointer to the DCB must point to the DCB’ that 
points to this UCB. 


U.SCB The pointer to the SCB must be even, must point 
within the data base, and the SCB to which it 
points must lie within the data base. 


U.RED The unit redirect pointer must be nonzero and even 
if it is an Executive address. If it is not an 
Executive address, it must be nonzero, even, and 
point within the data base. 


Each SCB is checked and relocated. The following offsets are both 
checked and relocated: 


S.KRB The pointer to the KRB must be even, must point 
within the data base, and the KRB to which it 
points must lie within the data base. If S.KRB is 
nonzero, there must be a CTB in the loadable data 
base. 


S.KTB If the table of KRB addresses is present, each 
entry must point within the data base. (PROLOD 
preserves bit zero in each entry.) Each entry in 
the table must also have a matching entry in the 
table of KRB addresses of a CTB in the loadable 
data base. 


The following offsets in each SCB are initialized as described: 

S.LHD The head of the I/O queue is set to zero and _ the 
pointer to the end of the queue (S.LHD+2) is set 
to point at S.LHD. 

S.PKT The pointer to the current I/O packet is set to l. 
These last checks end the loading and validating of the data base. 
After the data base is loaded and validated and no error is found, the 
driver itself is loaded into memory. In loading the driver, the 
driver dispatch table is validated, each interrupt entry in the driver 


dispatch table is inspected, and the vector(s) are checked. If a 
vector address is higher than the highest available vector address 


See) 
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PROLOD prints a warning message. Interrupt control blocks are created 
and linked into the list starting at L.ICB in the CTB. 


The format of the DDT must be consistent with that described in 


Section 4.3.1. If the device that the data base describes does not 
have any physical controllers (that is, a CTB does not exist), the DDT 
is not checked. Otherwise, the device has at least one interrupt 


vector and therefore at least one interrupt entry point. The DDT is 
then checked. The two global labels SxxTBL and SxxTRE must define the 
start and end of the DDT. The generic controller name(s) must be 
nonzero and the interrupt entry values must be valid. Interrupt entry 
point O must be nonzero, even, and lie in the range 117777 and 140000. 
If the format of DDT is inconsistent, PROLOD prints an error message, 
restores the system device tables, and exits. 


When the driver is loaded, all links are established. The DCB of the 
loadable data base is put in the list of DCBs just in front of the DCB 
for the first pseudo device. The CTB(s) are linked to the end of the 
CTB list. The DDT address D.DSP, the driver PCB address D.PCB, and 
the driver mapping S.KS5 (the block number of the first word of the 
driver) in the fork block are initialized. The address of the start 
of the KRB table in the CTB, denoted in the driver data base by the 
local label xxCTB, is loaded into the DDT. 


CHAPTER 6 


DEBUGGING A USER-SUPPLIED DRIVER 


Adding a user-supplied driver carries with it the risk of introducing 
obscure bugs into a P/OS system. Because the driver runs as part of 
the Executive, P/OS provides an Executive debugging tool (XDT). 


6.1 THE EXECUTIVE DEBUGGING TOOL 


XDT is an interactive debugging tool which can aid in debugging 
Executive modules, I/O drivers, and interrupt service routines. This 
debugging aid is similar to ODT, the task-level debugger. XDT 
occupies physical address space in the GEN partition but does not take 
up any Executive virtual address space. XDT also does not interfere 
with user-level ODT, which can be used with any number of tasks while 
you are debugging your driver with XDT. 


6.1.1 XDT Commands 


XDT commands are generally compatible with ODT commands. XDT does not 
contain the following commands available in ODT: 


@ No $M - (Mask) register 

@e No $X - (Entry Flag) registers 
@ No SV - (SST vector) registers 
@® No $D - (I/O LUN) registers 

e No SE - (SST data) registers 


@e No SW - (Directive status word) SDSW word 
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@ Nok - (Effective Address Search) command 
@ No F - (Fill Memory) command 

® NoN - (Not word search) command 

@ No V- - (Restore SST vectors) command 

e® No w - (Memory word search) command 


In addition, the X (Exit) command in XDT will simply issue a HALT 
instruction. This will drop the printer port terminal into Micro-ODT. 
(See Section 6.2. 


6.1.2 XDT Start Up 


You may install XDT from DCL with the command: INSTALL XDT/NOREMOVE. 
The "noremove" switch will inform the executive not to abort XDT when 
the DCL or Native Toolkit application exits. From DCL, RUN XDT. An 
initialization message will appear. When active, XDT runs entirely at 
priority level 7. 


6.1.3 XDT General Operation 


Prior to embarking on an XDT debugging session, plug a maintenance 
cable (BCC-08) into the printer port and attach a VT100 or similar 
terminal. If the cable had been in place when the system was’ turned 
on, the terminal will need to be set to 9600 baud; otherwise, the 
terminal must be at 4800 baud. Input and output are directed to this 
port. | 


Assemble the driver with an embedded BPT instruction, or use the ZAP 
utility to set the breakpoint by replacing a word of code with the BPT 
instruction. (Make sure to write down the instruction that you 
replace with the BPT instruction.) When the breakpoint instruction in 
the driver is executed, XDT prints: 


BE :XXXXXxX 
XDT> 


Then: 


1. Using XDT, replace the BPT instruction with the desired 
instruction. | 
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2. Decrement the PC by subtracting 2 from the contents of 
register R7. 


3. Then proceed by using the P or S commands, after optionally 
setting breakpoints within the driver or examining memory 
locations. 


6.1.4 XDT and Debugging a User-Supplied Driver 


Using XDT to debug a driver has special pitfalls. One problem that 
can arise is a T-bit error: 


TH? xx XXX 
XDT> 


This error results when control reaches a breakpoint that you _ have 
set, using XDT, in a loaded driver. The T-bit error, rather than the 
expected BE: error, occurs unless register APR5 is mapped to the 
driver at the time XDT sets the breakpoint. Assembling or zapping the 
BPT (as opposed to setting it from an XDT prompt) will help avoid this 
T-bit error. 


NOTE 


You should not set breakpoints in more than one module 
that maps into the Executive through APR 5 or APR 6. 
In particular, do not set breakpoints in more than one 
driver at atime or XDT will overwrite words of main 
memory when it attempts to restore what it considers 
to be the contents of breakpoints. 


6.2 MAINTENANCE- OR MICRO-ODT 


The processor microcode supports a more limited set of debugging 
commands which permit debugging of a system in an _ otherwise 
inaccessible state. Be advised, however, that Micro-ODT is able to 
access only the low 28K words of memory and the I/O Page, whereas XDT 
can be mapped to any part of memory. Micro-ODT is more _ fully 
documented in the Professional 300 Series Technical Manual. It will 


also be discussed further in this chapter. 
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6.3 FAULT ISOLATION 
Four causes can be identified when the system faults: 


1. A user-state task has faulted in such a way that it causes 
the system to fault. 


2. The user-supplied driver has faulted in such a way that it 
causes the system to fault. 


3. The system software itself has faulted. 

4. The hardware has faulted. 
When the system faults, you must first decide which of the above’ four 
potential causes is responsible. This section presents some 


procedures that can help you isolate the source of the fault. 
Correcting the fault itself is your responsibility. 


6.3.1 Immediate Servicing 


Faults manifest themselves in four ways as listed below (in order of 
increasing difficulty to isolate): 


1. If XDT is running, an unintended trap to XDT occurs. 
2. The system displays a software bugcheck and halts. 
3. The system halts but displays nothing. 

4, The system is in an unintended loop. 


The immediate aim, regardless of the fault manifestation, is to get to 
the point where you can obtain pertinent fault isolation data. 


6.3.1.1 The System Traps to XDT - A trap may or may not be intended 
(for example, a previously set breakpoint). If it is not intended and 
you have some idea of the source of the problem (for example, a recent 
coding change), you may use XDT to examine pertinent data structures 
and code. 


6.3.1.2 The System Halts but Displays No Information - Before taking 
any action, preserve the current PS and PC and the pertinent device 
registers (that is, examine and record the information these registers 
contain). See Section 6.2. 
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6.3.1.3 The System Is in an Unintended Loop - Proceed as follows: 


1. Halt the processor by pressing <BREAK> from the debugging 
terminal (Micro-ODT). 


2. Record the PC, the PS, and any pertinent device registers, as 
in Section 6.3.<1.2.% 


You may then want to step through a number of instructions in an 
attempt to locate the loop. Toggle the Micro-ODT Halt register by 
entering "H" at the "@" prompt. Following this, each "P" command will 


result in a single step. To restore "proceed" functionality to the 
"P" command, enter "H" again. 


In order to avoid the side-effects of printer port interrupts you may 
first wish to disable printer receiver interrupts. Then proceed as 
follows: 

1. In micro-ODT open location 173202 (the CSR). 


2. Set the printer receiver IMR (interrupt mask register) bit by 
depositing a 75 in this location. 


6.3.2 Pertinent Fault Isolation Data 
Before you attempt to locate the fault, you should examine the system 
common (SYSCM). SYSCM contains a number of critical pointers and 
listheads. In addition, you should examine the dynamic storage region 
(system pool and ICB pool) and the device tables. The device tables 
are in the module SYSTB. At this point, you have the following data, 
which represents a minimal requirement for effectively tracing the 
fault: 

@® PS 

@ PC 

@ The stack 

@® RO through R6 


@® Pertinent device registers 


@ The dynamic storage region 
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@ The device tables 


@e System common 


6.4 TRACING FAULTS 


Three pointers in SYSCM are critical in fault tracing. These pointers 
are described below: 


SSTKDP - Stack Depth Indicator 
This data item indicates which stack was being used at the time 


of the crash. SSTKDP plays an important role in determining the 
origin of a fault. The following values apply: 


+] -- User (task-state) stack or a privileged task at user 
state 
QO or less -- System stack 


If the stack depth is +l, then the user has crashed the system. 
STKTCB - Pointer to the Current Task Control Block (TCB) 

This is the TCB of the user-level task in control of the CPU. 
SHEADR - Pointer to the Current Task Header (Pool-Resident) 


The location of the task header and the contents of its associated 
pointers vary according to whether the task has an external header. A 
task with an external header has its header attached in a physically 
contiguous and numerically lower location in memory. A task with a 
nonexternal header has its header located in Executive pool space. 
Therefore, a header in Executive pool is a pool-resident header, and a 
header adjacent to the task is a non-pool-resident header. 


Figure 6-1 shows the interaction of header pointers’ for both 
pool-resident and non-pool-resident headers. For a pool-resident task 
header, SHEADR, SSAHPT, and SSAVSP all point to the first word of the 
task header. This word also contains the user task's stack pointer 
(SP) from the last time it was” saved. Figure 6-2 shows a brief 
description of the task header. The task header is fully described in 
the RSX1IM/M+ Task Builder Manual, which is distributed with the P/OS 
Toolkit Documentation. 
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POOL-RESIDENT TASK HEADER (Non-external) 


Virtual Header Addr. 


Current Task 


Saved Stack Addr. 
. Header 


Virtual Header Addr. 
| Saved Stack Pointer 


THDLN 0 


NON-POOL-RESIDENT TASK HEADER (External) 


. Task : 


Current Task 


Header 


SHEADR 


Executive 
Data Area 


% 


1-word block 


$SAVSP 


T.HOLN -0 


Executive 


Figure 6-l: Interaction of Task Header Pointers 


The header (as pointed to by $HEADR) also contains’ the last-saved 
register set, just before the header guard word (the last word in the 


header -- pointed to by H.GARD). 
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H.NLUN 


H.GARD 


H. HDLN Length in bytes 
| SP | 


Figure 6-2: Task Header 


The pointers associated with a pool-resident header are described 
next: 


SHEADR - Points to the current task header. 
The SHEADR word points to the pool-resident task header of 
the task currently running. The value in S$HEADR is a kernel 


virtual address in primary pool. 


SSAVSP - Points to the first word of the current task header, which 
contains the saved stack pointer. 


SSAHPT - Points to the current task header in pool. SSAHPT contains 
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the virtual address of the header. SSAHPT and SHEADR contain 
the same virtual address for a pool-resident header. 


SSAHDB -— Contents undefined 


The pointers associated with a non-pool-resident header are described 
nexts 


SHEADR - Points to the pointer for the saved stack pointer, SSAVSP. 

SSAVSP - Points to a 4-word block in the Executive data area. 

SSAHPT - Contains the octal value of 140000 that is to be used with 
SSAHDB to resolve the address of the task's header. $SAHPT 
always contains 140000 in this case. 

SSAHDB - Contains the value in KISAR6, which is a 32-word block-offset 


to be used with the value in SSAHPT to resolve the address of 
the task's header. 


6.4.1 Tracing Faults Using the Executive Stack and Register Dump 


The following discussion implies that XDT is active. If the system 
crashes while XDT is not active, a software bugcheck occurs. 
Procedures for analyzing a bugcheck are discussed in Section 6.4.5. 
To trace a fault after a software crash, first examine the system 
stack pointer. Usually an Executive failure is the result of an 
SST-type trap within the Executive. If an SST does occur within the 
Executive, then the origin of the call on the crash-reporting routine 
is in the SST service module. (The crash call is initiated by issuing 
an IOT at a stack depth of zero or less.) 


A call to crash also occurs in the Directive Dispatcher when an EMT is 
issued at a stack depth of zero or less, or a trap instruction is 
executed at a stack depth of less than zero. The stack structure in 
the case of an internal SST fault is shown in Figure 6-3. 


Figure 6-3: 
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Stack Structure: Internal SST Fault 


The fault codes are: 


>TRAPS TO 4 

*>MEMORY PROTECT VIOLATION 
*>BREAK POINT OR TRACE TRAP 

*IOT INSTRUCTION 

*ILLEGAL OR RESERVED INSTRUCTION 
*-NON RSX EMT INSTRUCTION 

*TRAP INSTRUCTION 

-11/40 FLOATING POINT EXCEPTION 
*>SST ABORT-BAD STACK 

*AST ABORT-BAD STACK 

*ABORT VIA DIRECTIVE 

*TASK LOAD READ FAILURE 

*TASK CHECKPOINT READ FAILURE 
>TASK EXIT WITH OUTSTANDING I/O 
*>TASK MEMORY PARITY ERROR 
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The PC points to the instruction following the one that caused the SST 
failure. The number of bytes is the number normally transferred to 
the user stack when the particular type of SST occurs. If the number 
is 4, then a non-normal SST fault occurred, and only the PS and PC are 
transferred. There are no SST parameters. 


If the failure is detected in S$DRDSP, the stack is the same as that 
shown in Figure 6-3, except that the number of bytes, the SST fault 


code (the fault codes are listed above), and the SST parameters are 
not present. 


One SST-type failure, stack underflow, does not result in the- stack 
structure of Figure 6-3. To determine where the crash occurred, first 
establish the stack structure. This can be deduced by the value of 
the SP and the contents of the top word on the stack. If the stack 
structure is that of Figure 6-3, then the failure occurred in SDRDSP, 
Or waS anormal SST crash. If the stack structure is that of Figure 
6-4, then an abnormal SST crash has occurred. 


Figure 6-4: Stack Structure: Abnormal SST Fault 


Abnormal SST failures occur when it is not’ possible to push 
information on the stack without forcing another SST fault. When this 
situation occurs, a direct jump to the crash-reporting routine is made 
rather than an IOT crash. The PS and PC on the stack are those of the 
actual crash, and the address printed out by the crash-reporting 
routine is the address of the fault rather than the address of the IOT 
that crashes the system. Note that the crash-reporting routine 
removes the PC and PS of the IOT instruction from the stack, which in 
this case is incorrect. Thus, the SP appears to be four bytes greater 
than it really is (as in Figure 6-4). 


You now have all the information needed to isolate the cause of the 
failure. From this point on, rely on _ personal experience and a 


knowledge of the interaction between the driver and_ the services 
provided by the Executive. 


6.4.2 Tracing Faults When the Processor Halts Without Display 


To trace a fault when the processor halts but displays no information, 
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first examine SSTKDP, STKTCB, SHEADR, SSAVSP, SSAHPT and SSAHDB. The 
difficulty in tracing failures in this case is that the system stack 
is not directly associated with the cause of a failure. 


By examining SSTKDP, you can determine the system state at the time of 
failure. If it was in user state, the next step is to examine the 
user’s stack. The examination focuses on scanning the stack for 
addresses that may be subroutine links that can ultimately lead to a 
thread of events isolating the fault. This is essentially the aim of 
looking at the system stack if SSTKDP is zero or less. 


Frequently, a fault can occur that causes the SP to point to Top of 
Stack (TOS)+4. This fault results from issuing an RTI when the top 
two items on the stack are data. The result is a wild branch and 
then, most probably, a halt. Figure 6-5 shows a case in which two 
data items are on the stack when the program executes an RTI. LOS 
points to a word containing 40100. Suppose that location 40100 
contains a halt. This indicates that the original SP was four bytes 
below the final SP, and fault tracing should begin from the original 
SP. 


Figure 6-5: Stack Structure: Data Items on Stack 


This type of fault also occurs when an RTS instruction is executed 
with an inconsistent’ stack. However, in that case, SP points to 
TOS+ 2% 


A scan of the contents of the general registers may give some hint as 
to the neighborhood in which a fault (or the sequence of events 
leading up to the fault) occurred. 


If the fault occurred in a new driver, a frequent source of clues is 
the buffer address and count words in the UCB (U.BUF, U.BUF+2, U.CNT), 
as are the activity flags (US.BSY and S.STS). Other locations in both 
the UCB and SCB may also provide information that may help locate the 
source of the fault. 
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6.4.3 Tracing Faults After an Unintended Loop 


To trace a fault when an unintended loop has occurred, first halt the 
processor by hitting <BREAK> from the debugging terminal. 


After you halt the processor, the same state exists as was discussed 
in Section 6.4.2. Follow a similar tracing procedure to the one 
described there. A specific suggestion is to check for a_= stack 
overflow loop. Patterns of data successively duplicated on the stack 
indicate a stack looping failure. 


6.4.4 Additional Hints for Tracing Faults 


Another item to check is the current (or last) I/O Packet, the address 
of which is’ found in S.PKT of the SCB. The packet function (I.FCN) 
defines the last activity performed on the unit. 


If trouble occurred in terminating an I/O request, a scan of the 
system dynamic memory region may provide some insight. This region 
starts at the address contained in $CRAVL, a cell in SYSCM. Because 
all I/O packets are built in system dynamic memory, their memory is 
returned to the dynamic memory region when they are successfully 
terminated. Following the link pointers in this region may reveal 
whether I/O completion proceeded to that point. In systems with QIO 
optimization, S$PKAVL (SYSCM) points to a list of I/O packet-sized 
blocks of dynamic memory that are not linked into the SCRAVL chain. 


A frequent error for an interrupt-driven device is to terminate an I/O 
Packet twice when the device is not properly disabled on I/0 
completion and an unexpected interrupt occurs. This action ultimately 
produces a double deallocation of the same packet of dynamic memory. 
Double deallocation of a dynamic buffer causes a loop in the module 
SDEACB on the next deallocation (of a block of higher address) after 
the second deallocation of the same block. At that time, R2 and _ R3 
both contain the address of the I/O Packet memory that has been doubly 
deallocated. 


6.4.5 System Bugcheck Without XDT 


If a software error causes the system to crash while XDT is not 
active, the system will bugcheck. A bugcheck will request the 
diagnostic ROM to display an unhighlighted picture of the Professional 
with a two-number code, for facility and type of bugcheck. Errors 
with a facility code of 000300 are executive or other system _ state 
errors, in which case, the type is represented in the following list: 


000000 IOT in System State 
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000001 Stack Overflow 

000002 Trace Trap or Breakpoint 

000003 Illegal Instruction Trap 

000004 Odd Address or Other Trap 4 
NOTE 


Since there are no odd address traps or memory parity 
errors on the 350, these traps are most likely NXM 
(non-existent memory), caused by illegal address 
computation, bus timeout, or memory management fault. 


000005 Segment Fault 


000006 A Background Task (one without a parent) aborted or 
exited with I/O outstanding 


The processing of the diagnostic ROM changes some of the context of 
the system at the time of the crash, so that the diagnosis of the 
problem is made somewhat more difficult. In particular, after a 
bugcheck, KISAR5, KISAR6, UISARO, and UISARI have been altered, and 
the Kernel Stack Pointer has not been preserved. You must’ therefore 
examine the Kernel stack from $STACK toward low memory in order to 
locate the trap. 


When the processor traps, the PSW and PC are pushed onto the stack. 
If the trap is a directive issued by a task in user state (i.e. an 
EMT trap), the task's general purpose registers are pushed beginning 
with R5 and ending with RO. Then the return call to $DIRXT and an 


initial DSW success code of 1 are pushed onto the_- stack. The 
directive processing may call other system subroutines, some of which 
might save R5 and R4 (by convention the "nonvolatile" registers). 


When the stack contents are analyzed to determine whether they are 
pointing to data structures or subroutine addresses, a picture of the 
flow of control can be outlined. Often there will be pointers on the 
Stack to UCB's or other driver-related structures, TCB'sS or _ other 
task-related structures, or saved APR mapping biases for temporary 
remapping of KISAR5 and KISAR6. Since most of these structures are in 
primary pool (and thus in the low 28KW of physical memory), they may 
be examined using micro-ODT. 


Ultimately, a crash will be preceded by a trap in system. state. 
Again, the PSW and PC at the time of the crash will be pushed onto the 
stack. A PSW of 0300nn or 000nnn indicates Kernel mode, previous mode 
User or Kernel, respectively. The PC will point to the instruction 
following the one causing the trap. Remember that after a bugcheck R6 
(or SP) will not point to this address on the stack. 
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6.5 REBUILDING AND REINCORPORATING A DRIVER 


After correcting and assembling the driver source, unload the old 
version using PROUNL, task build the new one, and load it using 
PROLOD. 


Once loaded, the data base is not removed by PROUNL. If the data base 
is in error and cannot be patched, correct its source, reassemble it, 
and build the new driver’ task. Then bootstrap the system _ before 
loading the driver task image containing the corrected data base. 


CHAPTER 7 


EXECUTIVE SERVICES AVAILABLE TO AN I/O DRIVER 


Because a driver is mapped within the Executive address space, it can 
call Executive routines on the same basis as that of any other module 
in the Executive. The driver must observe’ the protocol and 
conventions established on the- system. The following sections 
summarize the conventions, describe the address double word, tell what 
Special processing is required for NPR devices attached to a PDP-1l 
processor with extended memory support (22-bit addressing), and 
summarize some of the typical Executive services available. 


7.1 SYSTEM-STATE REGISTER CONVENTIONS 


In system state, R5 and R4 are, by convention, nonvolatile registers. 
This means that an internally called routine is required to save and 
restore these two registers if the routine destroys their contents. 
R3, R2, Rl, and RO are volatile registers and may be used by a called 
routine without save and restore responsibilities. 


When a driver is entered directly from an interrupt, it is operating 
at interrupt level, not at system state. At interrupt level, any 
register the driver uses must be saved and restored. INTSVS generates 
code to preserve R5 and R4 for the driver's use. All drivers must 
follow these conventions. 


See the description of the driver dispatch table in Section 4.5 for 
the contents of registers when a driver is entered. 


7.2 EXECUTIVE TIMER RELATED FACILITIES 


The executive provides a number of timer related facilities which are 
available to an I/O driver. They are typically used to periodically 
poll a device for a status change in the absence of an interrupt 
capability, to provide general timer services to the driver so that it 
can perform it's own timeout processing (needed by more advanced 
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drivers such as the full duplex terminal driver), or to call the 
driver back after some specified period of time. 


A timer request requires a structure called a clock block. It is 
normally located in the device driver's database which has been 
allocated from primary pool and is "C.LGTH" bytes in length. A driver 
can however simply allocate the clock block from primary pool using 
the SALOCB executive subroutine. The clock block contains the request 
type, the absolute time when request is to occur, and the bias and 
APR5 displacement of the driver routine to be called when inserted in 
the system clock queue. A timer request is made by calling the 
executive's SCLINS' routine. Input parameters to SCLINS are the 
virtual address of the primary pool resident clock block, the request 
type of "C.SYST", the high and low order time delta (in tics), and a 
unique identifier. "C.SUB" is expected to contain the virtual address 
of the driver routine to be called by executive's clock processor 
(executive module TDSCH) when the specified interval of time has 
elapsed. The unique identifier is used to dequeue timer requests 
before completion and must be a unique executive (primary pool) 
virtual address. This unique identifier could be a UCB address, or 
even the address of the clock block itself. Note that since this 
identifier is a system wide identifier, and an ad hoc value _ could 
potentially corrupt the system. 


Timer requests are one shot in nature and as such, the clock block is 
dequeued by the TDSCH processing. The request must be respecified via 
the SCLINS routine to achieve a periodic timer facility. The driver 
subroutine specified in the request will be called at system state at 
processor priority 0. 


If it is necessary to cancel a timer request, this may be done by 
removing the clock block from the system's clock queue via the 
executive's SCLRMV routine. The following examples further illustrate 
the manipulations required: 


-+- 


Example clock queue insertion and removal 
Driver database contains clock block in UCB and thus avoids resource 


allocation errors associated with dynamic allocation from primary 
pool. 


UCB 
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examples assume R5 => UCB 


=e @@ % @ 


The first example is a periodic polling of some device status. Though 
status changes are traditionally communicated to the driver via an 
interrupt, there are instances of when this hardware functionality is 
not available. 


=e 36 “=C€@ BES 


INITIM: MOV R5 ,RO -copy UCB address 
ADD #U.MYCB,RO spoint to clock block 
MOV #POLL,C.SUB(RO) ;specify address of timer routine 
CLR Rl zero high order delta time 
MOV #HSSRTZ/2,R2 sget number of ticks per half 
;second 


*for low order time delta 


Note that for a request type (6) "C.SYST" SCLINS will save 
current APR5 mapping and restore it when time delta expires 
before calling driver. The implication is that the virtual 
address specified in C.SUB must be mapped through APR5 and that 
the caller of SCLINS is also mapped through APR5 with the same 
mapping. If a request type (8) "C.SYTK" is specified, then the 
caller must have already specified the APR bias in C.AR5 in 
addition to the virtual address in C.SUB. Calling SCLINS after 
the clock block has already been inserted in the clock block can 
cause unpredictable results including the removal of other system 
timer requests as a result of the clock queue corruption. Should 
this be a problem, C.ROT could be used as an interlock by 
clearing it after clock queue removal and checking this word to 
determine if the clock block is in use before attempting to call 
SCLINS. 


=e we B=S BE BSE BWSH BH BW VS WE BE WH BWH WH WH VW WS 


MOV #C.SYST,R4 sspecify request type 
CALLR SCLINS sinsert clock block into clock 
*queue 
sand return to this subroutine’'s 
caller. | 
- The driver is called at this entry point every .5 seconds. All 
> registers may be used by the driver and upon entry, R4 contains 
* the address of the clock block dequeued. 
POLL: sfirst, respecify clock request 
MOV R4,R0 sspecify address of clock block 
CLR Rl sinit high order delta time 
MOV #HSSRTZ/2,R2 init low order delta time 
MOV C.TCB(RO),R5 sget address of identifier (UCB 
address despite symbolic offset 
>name) 
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snote that C.SUB is not modified 
sand still valid. 

CALL SCLINS ;respecify timer request 
snote that C.AR5, or C.SUB need 
;not be respecified. 


@=e BE 


On return from SCLINS, (RO,R4, and R5) are unmodified. 


: driver does what needs to be 
: | *done 
RETURN 


The second example builds on the first example and illustrates 
how to cancel a timer request. 


The CANTIM routine may be called to remove the clock block 
inserted above. 


@=e =6 BF ~“G@ BE BW WS 


CANTIM: MOV Ro, RL ;specify identifier of clock 
*block 
(in this case, the UCB address) 


A clock block may be removed from the system clock queue however, 
the listhead SCLKHD is not a double word listhead and therefore, 
SORMVT may not be called. SCLRMV can be called to remove clock 
blocks from the system clock queue and if the request type was 
not "C.SYST", the clock block will be deallocated from primary 
pool. Therefore, if the driver's clock block is located in the 
driver's database (such as in the UCB or KRB), only the request 
type "C.SYST" should be specified. 


=e ~eg BG WH ~™~e@ =O BW =o we % @ 


MOV #C.SYST,R4 specify type of request to 
; dequeue 

CALL SCLRMV dequeue it (if there) 

RETURN sreturn to caller 


723 ADDRESSING A TASK BUFFER 


A typical user task has no knowledge of the physical locations 
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every region mapped into its virtual space, since the physical 
addresses of a task's regions can change due to checkpointing or 
shuffling.* Given that a task can only specify the virtual address of 
a buffer to a system directive such as QIOS, this virtual address must 
be resolved to some form of an actual physical address being used 
while the issuing task's context is loaded. Most I/O operations’ are 
asynchronous to the execution of user tasks. As a result, the issuer 
could change its virtual address space mapping, and thus’ invalidate 
the specified virtual address. The executive assists the driver by 
keeping a count of all active I/O requests on a per region basis, and 
converting the user buffer virtual address in the first parameter to a 


physical address for transfer functions. If a region contains a 
non-zero I/O count, the executive will not checkpoint or shuffle the 
region. This would both invalidate the physical address and 


compromise the integrity of the system, since the outstanding I/O 
could be transferred into the another region resident in memory. 


For non-DMA devices, there are three common methods for a driver to 
reference a task buffer: 


1. The simplest approach is to move the "bias" half of the 
physical address double word into KISAR6 and then use the 
"displacement-in-block" half, which has been adjusted by the 
QIO directive processor to map through APR6 for transfer 
functions. Unless the bias and displacement are adjusted by 
the driver, the maximum size of the user task buffer is 
limited to <4096.-32.> words. 


2. In certain cases, it is not possible for the driver to unmap 
KISAR6 because another structure, such as an intermediate 
buffer (or possibly the driver code itself), is required to 
be mapped. These cases can use a method in which the 
executive SBLXIO routine is used to temporarily unmap_ the 
driver in KISAR5, map the source and destination buffers 
through KISAR5 and KISAR6. It then performs the transfer and 
restores the mapping. 


3. Another method is useful for drivers that sequentially empty 
or fill a task buffer word by word, or byte by byte. With 
this method, the executive's SGTBYT, S$GTWRD, SPTBYT and 
SPTWRD routines unmap KISAR6, perform the transfer, adjust 


* Checkpointing is the process of copying a region to a disk so it can 
be used by another contending region. Shuffling is the process of 
moving a region from one physical location to another location in 
order to reduce fragmentation. Though a fixed region or a 
non-checkpointable region cannot be checkpointed, it can be shuffled - 
provided the region has a zero I/O count and is not explicitly marked 
as non-shufflable (PS.NSF). 
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the bias and displacement of the target buffer. The buffer 
could be as large as 32KW and restore the KISAR6 mapping (see 
module BFCTL). 


7.3.1 Address Checking a Task Buffer 


Address checking is the process of validating that a buffer is fully 
mapped within the task's virtual address space, that a buffer is 
contained within one region, and that the issuing task has write 
access to the region. A buffer can be checked for read only access or 
read/write access, depending upon the I/O function. For instance, an 
TO.WLB or I0O.WVB’- check the buffer for read-only access, since it is 
known that the transfer will not write to the region. Normally, a 
driver does not need to explicitly address check the I/O buffer, as 
the executive's QIOS directive (see DRQIO) assumes this function for 
transfer and ACP I/O functions. 


7.3.2 QIO Directive Processing Specifics 


The following checks and actions are performed by the executive's QIO 
directive processing: 


® The specified LUN must be valid and assigned. If it is not, 
a directive error IE.ILU or IE.ULN is returned. 


e The UCB address in LUN is resolved to the target UCB by 
following the redirect pointer U.RED. 


e If I/O is stalled for the unit (US.SIO=1) or if ae file 
operation is pending (bit 0 in the second LUN word =1), the 
issuing task's PC is modified so that the directive is 
reissued at a later point in time after a significant event 
occurs. The Files-ll reverification task (VER...) is allowed 
to break through a stalled I/O state. 


@e The driver must be resident. If not, a directive error 
(IE.HWR) is returned. 


@® If an optional event flag is specified, it is validated and 
cleared. Lf an invalid (non-existent) event flag is 
specified, a directive error (IE.IEF) is returned. 


@ An I/O packet is allocated from the primary pool. If there 
is insufficient pool to create the I/O packet, a directive 
error (IE.UPN) is returned. 
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If the directive QIOWS is received, the task is placed in a 
“waitfor" state - if the event flag was specified. 


An I/O rundown count (T.IOC) is incremented in the issuer's 
task control block. 


The optional I/O status block is validated, and the contents 
cleared. The virtual address and physical address double 
word of the I/O status block are stored in the I/O packet. 


I/O packet fields are initialized and used as indicated in 
Table 7-2. 


IO.KIL functions are always’ legal and are processed 
immediately by the executive. The driver's I/O packet queue 
(listhead S.LHD) is flushed, whether the unit is online or 
not, of all packets with the same TCB address and UCB address 
if the device is not mounted with an associated ACP. If the 
unit is online and cancel notification has been requested by 
the driver (UC.KIL=1), the driver is always called at _ the 
D.VCAN entry point - independent of whether the unit was busy 
or if any packets were flushed. If the unit was busy at the 
time of the cancel I/O request, the driver will be called. 


Depending on device characteristics, unit status, and type of 
function, specific processing is performed and the I/O packet 
is either queued to the driver or to the ACP. 


Table 7-1: QIO Processing By Function Type and Device Characteristics 
DV.MNT | TYPE | US.MNT| US.FOR| US.LAB|] Checks and action performed 

-------- $—-----~4}-------4----- - - 4 - - - - - eee 

0 N _ - ~ 1,2,1S.SUC is returned 

0 C = = - Lele 

0 ak - - - lg2¢B 

0 A - - - Lg2eouD 

1 N ~ ~ ~ 2,1S.SUC is returned 

| C 1 - = op Ghe 6 

1 at 1 - - 2,4,B,6 

1 A 1 - - 252 

1 C 0 1 - 2.1 Age 

1 C 0 0 zh 2,/,A,6 

1 C 0 0 0 21 K76 

1 E 0 | - 2, 34B;6 

1 T 0 0 - 2: 4.94B; 6 

1 A 0 1 - 2404 CHO 

1 A 0 0 - (beyond scope of this table) 
where 


PHO 
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NOP 
Control 
Transfer 
ACP 


If the device unit is allocated (U.OWN <> 0 ), and not public 
(US.PUB=0), then an I/O error of IE.PRI is return unless the 
issuing task is privileged or the issuing task's TI is’ the 
allocator ((T.UCB)=(U.OWN)). 


If the function is not legal then an I/O error of IE.IFN is 
returned. Also, if the device unit is marked offline 
(US.OFL=1) then an I/O error of IE.OFL is returned. 


If function code is I0.RVB ((I.FCN+1)=I0.RVB/~0400) then 
function code is converted to IO.RLB and all subfunction bits 
cleared. If function code is an IO.WVB, then subfunction is 
converted to an IO.WLB again clearing all subfunction bits. 


If device unit's volume status is not valid (US.VV=0) an I/O 
error of IE.PRI is returned. 


ACP functions to a dismounted volume result in an  IE.PRI 
error. 


Task load overlay checks. IO.LOV and 1I0.LOD have a 
particular meaning for mountable devices, whether or not 
device is mounted or not, and check is’ performed for both 
control and transfer functions. (These I/O functions are 
equivilent to IO.RLB!10 or IO.RLB!110 .) 


Control functions to a mounted ANSI tape required the issuer 
to be privileged. 


An ACP must be associated with the unit otherwise an I/O 
error of IE.PRI is returned. 


A transfer-function to a mounted volume must be a load 
overlay function or the task must be privileged. 


A. A control function format I/O packet is built and queued 
to the driver. 


B. A transfer function format I/O packet is built and queued 
to the driver. If the I/O function was an IO.WVB or an 
IO.WLB, then the buffer is address checked for read only 
access, otherwise the buffer is checked to ensure that 
the task has write access to the buffer's region. 
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C. Same action as B except that packet is queued to ACP. 


Table 7-2: I/O Packet Usage by Function Type 


I/O packet Control Transfer 

Field Functions Functions Notes 
1. LNK a Gees Tene word a 
LE PRI (T.PRI) (T.PRI) 

I .EFN (QO. IOLU) (Q.IOLU) 

T.0CB (STKTCB) (STKTCB) 1 
I.LN2 (SHEADR)+H.NLUN+2+<<Q. IOLU-1>*4>+2 Z 
I.UCB redirected UCB address 3 
I.FCN (O. IOFN) (Q.IOFN) 4 
I.IOSB virtual address of I/O status block 5 
I. 1OSBt+2 bias of I/O status block 5 
I. 1OSBt+4 disp. in blck+140000 of I/O status blck 5 
I.AST virtual address of I/O completion AST 
I.PRM (Q.IOPL) bias of buffer 

I .PRM+2 (Q.IOPL+2) DIB+140000 of buf. 
I.PRM+4 (Q.IOPL+4) (Q.IOPL+2) 

I .PRM+6 (Q.IOPL+6) (Q.IOPL+4) 

I.PRM+10 (Q.IOPL+10) (O.1OPL+6) 

I.PRM+12 (Q.IOPL+12) (Q.IOPL+10) 

I.PRM+14 0 (Q.IOPL+12) 

I.PRM+16 0 0) 

I.AADA 0 address of ADB 8 
I .AADA+2 0 0 


Notes: 
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If the high bit in the event flag byte field is set, it 
indicates a virtual I/O function. I.PRM+16 is then treated 
as a FILES-11 lock block during I/O completion. Mass storage 
device drivers should ensure that I.PRM+16 is not used as 
temporary storage of I/O context. 


If the bit O is set in the contents (not the address) of the 
second LUN word I.LN2, it indicates that this word contains 
the window block pointer. If the function is virtual and 
this word is even, the task'’s header (task region) has been 
locked in memory by incrementing the attachment descriptor 
I/O count and the task region's PCB I/O count. 


UCB addresses in the task header are not fully resolved to 
the target UCB, so a level of indirection is possible. For 
instance, a task which is preinstalled in the system before 
boot may need to read a disk overlay from LB:. The UCB 
address of the pseudo device LB: is in the LUN, and_ the 
system has redirected the pseudo device to the physical boot 
unit during the boot process to DWl:, DZ1l:, or DZ2:. 


The I.FCN word consists of two bytes. The high byte is’ the 
function code and the low byte is the subfunction code. The 
subfunction consists of eight independent bits which are 
interpreted within the context of the function code. The 
exceptions are as follows: 


e The subfunction IQ.UMD (4) stamps any I/O function as a 
diagnostic FUNCTION; independent of any device 
characteristics. 


@e The subfunction IQ.X (1) means inhibit reties. It is of 
primary interest to mass storage device drivers. 


@e The subfunction IQ.LCK (~0200) is used by FILES-1l1l ACP 
functions and will not be seen normally by the mass 
storage device driver. 


@e Another subfunction bit of concern to mass storage device 
drivers occurs when "write checking" is requested on a 
mounted volume. This is indicated by an IO.WLB function 
with subfunction bit (20) specified. 


I/O counts are not maintained for the I/O status'7 block. 
Therefore, the I/O status block may not be accessed by the 
driver except at predriver initialization time (UC.QUE=1). 
I/O completion processing uses the physical address of the 
I/O status block, provided no event has occurred while I/O 
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was outstanding that would have invalidated this address 
(such as unmapping a region, an EXTKS, or a checkpoint), as 
indicated by T3.MPC. If such an event has occurred, the I/O 
packet is converted into a kernel AST packet such that when 
the task’s context is loaded, the virtual address can be 
used. Note that system's integrity is preserved here, rather 
than the issuing task's, if the task remapped or unmapped the 
I/O status block. In general, a task may not change the 
virtual mapping of it’s I/O status block, but can unmap an 
1/O buffer if needed. 


If I.IOSB+4 is odd, it indicates that the I/O packet is 
internal I/O which was issued from another driver or system 
process. When I/O is completed, a specified kernel mode 
completion routine is called - rather than performing normal 
I/O completion processing (see SIOFIN in IOSUB for details). 
This is intended to be transparent to the driver. 


7.4 THE ADDRESS DOUBLE WORD 


P/OS can accommodate configurations whose maximum physical memory is 
2048K words. Individual tasks, however, are limited to 32K words. 
The addressing is accomplished by using virtual addresses and memory 
mapping hardware. I/O transfers, however, use physical addresses 18 
bits in length. Since the PDP-11l word size is 16 bits, some scheme is 
necessary to represent an address internally until it is actually used 
in an I/O operation. The choice was made to encode two words as_ the 
internal representation of a physical address and to transform virtual 
addresses for I/O operations into the internal doubleword format. 


On receipt of a QIO directive, the buffer address in the Directive 
Parameter Block, which contains a task virtual address, is converted 
to address doubleword format. 


The virtual address in the DPB is structured as follows: 


Bits O through 5 Displacement in terms of 32-word blocks 
Bits 6 through 12 Block number 
Bits 13 through 15 Page Address Register Number (PAR#) 


The internal P/OS translation restructures this virtual address into 
an address doubleword as described in the following paragraphs. 


THE ADDRESS DOUBLE WORD 


The relocation base contained in the PAR specified by the PAR number 
in the virtual address in the DPB is added to the block number in the 
address. The result becomes the first word of the address doubleword. 
It represents the nth 32-word block in a memory viewed as a collection 
of 32-word blocks. Note that at the time the address doubleword is 
computed, the user's task issuing the QIO directive is mapped by the 
processor's memory management registers. 


The second word is formed by placing the displacement in block (bits 0 
through 5 of virtual address) into bits 0 through 5. The block number 
field was accommodated in the first word and bits 6 through 12 are 
cleared. Finally, a6 is placed in bits 13 through 15 to enable use 
of PAR #6, which the Executive uses to service I/O for program 
transfer devices. | 


For nonprocessor request (NPR) devices, the driver requirements’ for 
manipulating the address doubleword are direct and are discussed with 
the description of U.BUF in Section 4.4.4. 
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This section contains general commentary on the Executive routines 
typically used by I/O drivers. The descriptions of the routines are 
taken from the source code of modules linked to form the Executive. 
Table 7-3 summarizes the routines described in this section. Only the 
most widely used routines are described; however, many other Executive 
services are available. The source code for the related routines is 
in the MACRO-11 source files for the Executive modules. 
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Table 7-3: Summary of Executive Service Calls for Drivers 


Routine Location in 
Module 

Name Function 
SACHKB EXSUB Address check for byte-aligned buffers 
SACHCK EXSUB Address check for word-aligned buffers 
SALOCB CORAL Alocate core buffer 
SBLKCK MDSUB Check logical block number 
SBLKCl MDSUB Check logical block number 
SBLKC2 MDSUB Check logical block number 
SBLXIO BFCTL Move block of data 
SCKBFI EXESB Check I/O buffer 
SCKBFR EXESB Check I/O buffer 
SCKBFW EXESB Check I/O buffer 
SCKBFB EXESB Check I/O buffer 
SCLINS QUEUE Clock queue insertion 
SCVLBN MDSUB Convert logical block number 
SDEACB CORAL Deallocate core buffer 
S FORK SYSXT Create a fork process 
SFORK1 SYSXT Fork but bypass clearing timeout count 
SGTBYT BFCTL Get byte 
SGTPKT IOSUB Get an I/O packet 
SGSPKT IOSUB Get a special I/O packet 
SGTWRD BFCTL Get word 
SINIBF TOSUB Initiate I/O buffering 
SINTXT SYSXT Interrupt exit 
SIOALT IOSUB Alternate entry to SIODON 
SIODON IOSUB I/O done for completing an I/O request 
SIOFIN ITOSUB I/O finish for special I/O completion 
SPTBYT BFCTL Put byte 
$PTWRD BFCTL Put word 
SQINSP QUEUE Queue insertion by priority 
SRELOC MEMAP Relocate address 
SREQUE ITOSUB Queue kernel AST to task 
SREQU1 LTOSUB Queue kernel AST to task 
STSPAR REQSB Test if partition memory resident 

for kernel AST 

STSTBF IOSUB Test for I/O buffering 
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SACHKB 
SACHCK 


7.5.1 Address Check 
These routines are in the file IOSUB. A driver can call either 
routine to address-check a task buffer while the task is the current 


task. The Address Check routines are normally used only by drivers 
setting UC.QUE in U.CTL. See Section 8.1 for an example. 


Calling Sequences: 
CALL SACHKB 
or 
CALL SACHCK 
Description: 
-- 
**-SACHKB-ADDRESS CHECK BYTE ALIGNED 
**_-SACHCK-ADDRESS CHECK WORD ALIGNED 


THIS ROUTINE IS CALLED TO ADDRESS CHECK A BLOCK OF MEMORY TO SEE 
WHETHER IT LIES WITHIN THE ADDRESS SPACE OF THE CURRENT TASK. 


INPUTS: 


RO=STARTING ADDRESS OF THE BLOCK TO BE CHECKED. 
R1=LENGTH OF THE BLOCK TO BE CHECKED IN BYTES. 


OUTPUTS : 


C=1 IF ADDRESS CHECK FAILED. 
C=0 IF ADDRESS CHECK SUCCEEDED. 


R2 =ADDRESS OF WINDOW BLOCK MAPPING BUFFER 
(FOR PRIV TASKS SEE NOTE.) 


RO AND R3 ARE PRESERVED ACROSS CALL. 


NOTE 3: SINCE PRIVILEGED TASK I /O BUFFERS ARE NOT 
ADDRESS CHECKED, R2 ALWAYS RETURNS A POINTER TO 
THE FIRST WINDOW BLOCK. CHECKPOINTING AND 
SHUFFLING OF COMMONS WILL STILL WORK PROPERLY 
PROVIDED THAT A PRIVILEGED TASK NEVER SPECIFIES 
AN I /O INTO A COMMON WHICH IT ALLOWS TO REMAIN 


™=@ "@ ™=6 =O RWS TH RQ BQ BWSE WH WH WHE WH WH WH WH VS WH WH WH WH WHE WH WH BH WHE WE @W 
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CHECKPOINTABLE AND SHUFFLEABLE. 


In P/OS, almost all drivers will wish to use the alternate 
routines SCKBFB/SCKBFW which correctly maintain the 
attachment and partition I/O count mechanism in addition to 
address checking the user buffer. If the driver completes 
all references to the buffer in the initiation routine (that 
is, fills the buffer and calls SIOFIN, rather than queueing 
the packet and/or starting a transfer which is completed via 
interrupt service) then it is permissible to use 
SACHKB/SACHCK. See Section 7.5.5 for a description of 
SCKBFB/SCKBFW and Section 8.1 for an example. 
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SALOCB 


7.5.2 Allocate Core Buffer 


This routine is in the file CORAL. 


Calling Sequences: 


CALL SALOCB 
or 

CALL SALOC1 
Description: 

e+ 


**-SALOCB-ALLOCATE CORE BUFFER 
**-SALOC1-ALLOCATE CORE BUFFER (ALTERNATE ENTRY) 


THIS ROUTINE IS CALLED TO ALLOCATE AN EXEC CORE BUFFER, THE 
ALLOCATION ALGORITHM IS FIRST FIT AND BLOCKS ARE ALLOCATED IN 
MULTIPLES OF FOUR BYTES. 


=6@ =6 =~G6 @=6 =@~O WH BW WS 


INPUTS: 


RO=ADDRESS OF CORE ALLOCATION LISTHEAD-2 IF ENTRY AT 
SALOC1] R1=SIZE OF THE CORE BUFFER TO ALLOCATE IN BYTES. 


OUTPUTS : 


IF INSUFFICIENT CORE IS AVAILABLE TO ALLOCATE THE 
BLOCK. 

C=0 IF THE BLOCK IS ALLOCATED. 

RO=ADDRESS OF THE ALLOCATED BLOCK. 

RI1=LENGTH OF BLOCK ALLOCATED 


=e = BS WE WE WE WH WH WE VBWSE WE WES 
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SBLKCK 
SBLKCl 
SBLKC2 


lade 
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Check Logical Block 


This routine is in the file MDSUB. The output from this routine is 
used by disk drivers as input to the SCVLBN routine to handle logical 
block numbers in data transfers. 


Calling Sequence: 


CALL SBLKCK 


Or 


CALL SBLKC2 


Descriptions: 


wee Be ™e~e BSF BZWE BBW WS =e BE BS ™~Se@ BS BWE 


w~e ™@~@ BE WH WH BSH BVH BWSH WS WH WH WE WHE WH WH 


oj 


**-SBLKCK-LOGICAL BLOCK CHECK ROUTINE 

**-SBLKCI-LOGICAL BLOCK CHECK ROUTINE (ALTERNATE ENTRY) 

**-SBLKC2-LOGICAL BLOCK CHECK ROUTINE (ALTERNATE ENTRY FOR 
QUEUE OPT) 


THIS ROUTINE IS CALLED BY I/O DEVICE DRIVERS TO CHECK THE 
STARTING AND ENDING LOGICAL BLOCK NUMBERS OF AN I/O TRANSFER TO 
A FILE STRUCTURED DEVICE. IF THE RANGE OF BLOCKS IS NOT LEGAL, 
THEN SIODON IS ENTERED WITH A FINAL STATUS OF "IE.BLK" AND A 
RETURN TO THE DRIVER'S INITIATOR ENTRY POINT IS EXECUTED. ELSE 
A RETURN TO THE DRIVER IS EXECUTED. 


SBLKC2 RETURNS TO SQOPDN IN SDRORQ IF THERE IS AN ERROR INSTEAD 
OF THE DRIVER'S INITIATOR ENTRY POINT. THIS ALLOWS THE QUEUE 
OPTIMIZATION CODE TO USE BLKCK 

INPUTS: 


R1=ADDRESS OF I/O PACKET. 
R5=ADDRESS OF THE UCB. 


OUTPUTS: 
IF THE CHECK FAILS, THEN SIODON IS ENTERED WITH A FINAL 
STATUS OF "IE.BLK" AND A RETURN TO THE DRIVER'S INITIATOR 
ENTRY POINT IS EXECUTED. 


IF THE CHECK SUCCEEDS, THEN THE FOLLOWING REGISTERS ARE 
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RETURNED: 
RO=LOW PART OF LOGICAL BLOCK NUMBER. 
R1=POINTS TO I.PRM+12 (LOW PART OF USER LBN) 
R2=HIGH PART OF LOGICAL BLOCK NUMBER. 
R3=ADDRESS OF I/O PACKET. 


SERVICE CALLS 


SBLXIO 


7.5.4 Move Block of Data 
This routine is in file BFCTL. 
Calling Sequence: 

CALL SBLXIO 


Description: 


~e 


**-SBLXIO-MOVE BLOCK OF DATA. 


THIS ROUTINE IS CALLED TO MOVE DATA IN MEMORY IN A MAPPED 
SYSTEM. 


INPUTS: 


RO=NUMBER OF BYTES TO MOVE. 
R1=SOURCE APR5 BIAS. 
R2=SOURCE DISPLACEMENT. 
R3=DESTINATION APR6 BIAS. 
R4=DESTINATION DISPLACEMENT. 


OUTPUTS: 


DESCRIBED MOVE IS ACCOMPLISHED. 

RO ALTERED 

R1,R3 PRESERVED 

R2,R4 POINT TO LAST BYTE OF SOURCE AND DESTINATION + 1 


NOTE: THE COUNT INPUT IN RO MUST NOT BE ZERO AND IT MUST 
NOT BE LARGE ENOUGH TO CROSS APR BOUNDARIES (THIS 
TYPICALLY MEANS A MAXIMUM OF 8KB-64.BYTES). 
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SCKBFI 
SCKBFR 
SCKBFW 
SCKBFB 
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Check I/O Buffer 


These routines are in file EXESB. 


Calling Sequences: 


CALL 


Description: 


te =e BE =e ™=Se Se BE BS BE WS Se =S BE =¢e 


=e 
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SCKBFB (or appropriate entry name) 


**-SCKBFI-CHECK I/O BUFFER FOR I-SPACE (OVERLAY) ACCESS 
**-SCKBFR-CHECK I/O BUFFER FOR READ-ONLY (BYTE) ACCESS 

**-SCKBFW-CHECK I/O BUFFER FOR READ-WRITE (WORD) ACCESS 
**_SCKBFB-CHECK I/O BUFFER FOR READ-WRITE (BYTE) ACCESS 


THESE ROUTINES ARE CALLED TO ADDRESS CHECK AN I/O BUFFER 
ASSOCIATED WITH THE CURRENT (UNDER CONSTRUCTION) I/O PACKET. 
IF THE ADDRESS CHECK PASSES, THEN AN ATTEMPT IS MADE TO POINT 
ONE OF THE ATTACHMENT DESCRIPTOR POINTERS AT THE ASSOCIATED 


ADB. 


1) = 


2) = 


ay: te 


THIS WILL HAVE ONE OF THE FOLLOWING OUTCOMES: 


THERE IS CURRENTLY NO ATTACHMENT POINTER IN THE PACKET TO 
THIS ADB, AND THE POINTERS AREN'T FULL. A POINTER IS FILLED 
IN AND THE A.IOC, P.IOC FIELDS FOR THIS I/O ARE 
INCREMENTED. THIS IS THE "NORMAL" SUCCESSFUL CASE. 


THERE IS ALREADY ONE POINTER TO THIS ADB. THE PACKET IS 
UNTOUCHED, AS ARE THE A.IOC AND P.IOC FIELDS, AND THE CHECK 
IS CONSIDERED SUCCESSFUL. THE IMPLICATION OF NOT 
INCREMENTING A.IOC AND P.IOC IS THAT DRIVERS AND ACPS MAY 
NOT RELEASE BUFFERS FOR AN I/O REQUEST ONE AT A TIME, I.E. 
THE DRIVER SHOULD NOT CALL SDECIO DIRECTLY, BUT SHOULD CALL 
SIODON OR SDECAL AFTER ALL BUFFER ACCESS HAS COMPLETED. 


THERE ARE ALREADY TWO POINTERS, NONE OF THEM TO THIS 
ATTACHMENT DESCRIPTOR. THIS IS CONSIDERED A CHECK FAILURE 
AND RETURN IS MADE WITH CARRY SET. 


INPUTS: 


RO=STARTING ADDRESS OF BLOCK TO BE CHECKED 
RIL=LENGTH OF BUFFER TO BE CHECKED 
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SATTPT=ADDRESS OF I.AADA IN CURRENT I/O PACKET 
HEADER OF THE SUBJECT TASK IS MAPPED THROUGH KISAR6 


OUTPUTS: 


C=0 CHECK AND PACKET UPDAT SUCCESSFUL 
I.AADA OR I.AADA+2 POINTS TO THE ADB 
A.IO0C, P.IOC INCREMENTED 
C=1 CHECK UNSUCCESSFUL OR PACKET COULD NOT BE FILLED IN 


SERVICE CALLS 


SCLINS 


725-6 Clock Queue Insertion 
This routine is in the file QUEUE. 
Calling Sequence: 

CALL SCLINS 


Description: 


-- 


**-SCLINS-CLOCK QUEUE INSERTION 


THIS ROUTINE IS CALLED TO MAKE AN ENTRY IN THE CLOCK QUEUE. THE 
ENTRY IS INSERTED SUCH THAT THE CLOCK QUEUE IS ORDERED IN 
ASCENDING TIME. THUS THE FRONT ENTRIES ARE MOST IMMINENT AND 
THE BACK LEAST. 


INPUTS: 


RO=ADDRESS OF THE CLOCK QUEUE ENTRY CORE BLOCK. 
R1=HIGH ORDER HALF OF DELTA TIME. 

R2=LOW ORDER HALF OF DELTA TIME. 

R4=REQUEST TYPE. 

R5=ADDRESS OF REQUESTING TCB OR REQUEST IDENTIFIER. 


OUTPUTS: 


THE CLOCK QUEUE ENTRY IS INSERTED IN THE CLOCK QUEUE 
ACCORDING TO THE TIME THAT IT WILL COME DUE. 
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SCVLBN 


7.5.7 Convert Logical Block Number 


This routine is in the file MDSUB. The input to this routine is’ the 
same as the output from the S$BLKCK routine. Typically, a disk driver 
calls this routine to convert a logical block number to a= physical 
disk address. The routine accesses the U.PRM fields in the driver 
data base unit control block. These fields contain the sector, track, 
and cylinder parameters for the type of disk Supported. Refer to the 
description of the U.PRM fields in Section 4.4.4. 


Calling Sequence: 
CALL SCVLBN 


Description: 


ole 


**-SCVLBN-CONVERT LOGICAL BLOCK NUMBER TO DISK PARAMETERS 


THIS SUBROUTINE WILL CONVERT THE SPECIFIED LOGICAL BLOCK 
NUMBER TO A SECTOR/TRACK/CYLINDER ADDRESS. 


INPUTS: 


(SAME AS SBLKCK OUTPUTS) 
RO=LOW PART OF LBN 
R2=HIGH PART OF LBN 
R3=I1/O PACKET ADDRESS 
R5=UCB ADDRESS 


OUTPUTS 's 
RO=SECTOR NUMBER 


R1=TRACK NUMBER 
R2=CYLINDER NUMBER 
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SERVICE CALLS 


SDEACB 


7.5.8 Deallocate Core Buffer 
This routine is in the file CORAL. 
Calling sequences: 

CALL SDEACB 
or 

CALL SDEAC1] 


Description: 


~f- 


**-SDFACB-DEALLOCATE CORE BUFFER 


INPUTS : 


RO=ADDRESS OF THE CORE BUFFER 

R1=SIZE OF THE CORE BUFFER TO 

R3=ADDRESS OF CORE ALLOCATION 
SDEAC1. 


OUTPUTS : 
THE CORE BLOCK IS MERGED INTO 


ADDRESS AND IS AGLOMERATED IF 
BLOCKS. 
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**—SDEAC1-DEALLOCATE CORE BUFFER (ALTERNATE ENTRY) 


THIS ROUTINE IS CALLED TO DEALLOCATE AN EXEC CORE BUFFER. THE 

BLOCK IS INSERTED INTO THE FREE BLOCK CHAIN BY CORE ADDRESS. IF 
AN ADJACENT BLOCK IS CURRENTLY FREE, 
MERGED AND INSERTED IN THE FREE BLOCK CHAIN. 


THEN THE TWO BLOCKS ARE 


TO BE DEALLOCATED. 
DEALLOCATE IN BYTES. 
LISTHEAD-2 IF ENTRY AT 


THE FREE CORE CHAIN BY CORE. 
NECESSARY WITH ADJACENT 


SERVICE CALLS 


SFORK 


led.9 Fork 

Fork is in the file SYSXT. A driver calls S$FORK to switch from a 
partially interruptable level (its state following a call on SINTSV) 
to a fully interruptable level. 

Calling sequence: 


Description: 


- 


**—SFORK-FORK AND CREATE SYSTEM PROCESS 


THIS ROUTINE IS CALLED FROM AN I/O DRIVER TO CREATE A SYSTEM 
PROCESS THAT WILL RETURN TO THE DRIVER AT STACK DEPTH ZERO TO 
FINISH PROCESSING. 


INPUTS: 


R5=ADDRESS OF THE UCB FOR THE UNIT BEING PROCESSED. 
0(SP)=RETURN ADDRESS TO CALLER. 
2(SP)=RETURN ADDRESS TO CALLERS CALLER. 


OUTPUTS : 


REGISTERS R5 AND R4 ARE SAVED IN THE CONTROLLER FORK BLOCK 
AND A SYSTEM PROCESS IS CREATED. THE PROCESS IS LINKED TO 
THE FORK QUEUE AND A JUMP TO SINTXT IS EXECUTED. 
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Notes: 


1. S$FORK cannot be called unless SINTSV has’ been previously 
called or SINTSI has run. The fork-processing routine 
assumes that the Executive has set up entry conditions. 


2. A driver's current timeout count is cleared in calls to 
SFORK. This protects the driver from _ synchronization 
problems that can occur when an I/O request and the timeout 
for that request happen at the same time. After a return 
from a call to $FORK, a driver's timeout code will not _ be 
entered. 


SERVICE CALLS 


If the clearing of the timeout count is not desired, a driver 
has two alternatives: 


Es 


Perform timeout operations by directly inserting elements 
in the clock queue (refer to the description of the 
SCLINS routine). 


Perform necessary initialization, including clearing 
S.STS in the SCB to zero (establishing the controller as 
not busy), and call the $FORK1 routine rather than $FORK. 
Calling SFORK1 bypasses the clearing of the current 
timeout count. 


The driver must not have any information on the stack when 
SFORK is called. 


SFORK1 


SERVICE CALLS 


7.5.10 Forkl 


Forkl is 
clearing 
interrupt 
descripti 
Calling §S 
CALL 


Descripti 
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Notes: 


in the file SYSXT. A driver calls S$FORK1 to bypass’ the 
of its timeout count when it switches from a partially 


able level to a fully interruptable level (refer also to’ the 
on of the SFORK routine). 
equence: 
SFORK1 
on: 
-SFORK1-FORK AND CREATE SYSTEM PROCESS 
IS ROUTINE IS AN ALTERNATE ENTRY TO CREATE A SYSTEM PROCESS 
D SAVE REGISTER R5. 
PUTS: 
R4=ADDRESS OF THE LAST WORD OF A 3-WORD FORK BLOCK PLUS 2. 
R5=REGISTER TO BE SAVED IN THE FORK BLOCK. 
TPUTS: 


REGISTER R5 IS SAVED IN THE SPECIFIED FORK BLOCK AND A 
SYSTEM PROCESS IS CREATED. THE PROCESS IS LINKED TO THE 
FORK QUEUE AND A JUMP TO SINTXT IS EXECUTED. R5 IS 
RESERVED FOR CALLERS CALLER. 


A 5-word fork block is required for calls to $FORKI1. 


When a 5-word fork block is used, the driver must initialize 
the fifth word with the base address (in 32-word blocks) of 
the driver partition. This address can be obtained from the 
fifth word of the standard fork block in the SCB. 


The driver must not have any information on the stack when 
SFORK1] is called. 


SERVICE CALLS 


SGTBYT 


7.5.11 Get Byte 


Get Byte is in the file BFCTL. Get Byte manipulates words U.BUF and 
U.BUF+2 in the UCB. 


Calling sequence: 
CALL SGTBYT 


Description: 


of. 


**-GTBYT-GET NEXT BYTE FROM USER BUFFER 
THIS ROUTINE IS CALLED TO GET THE NEXT BYTE FROM THE USER BUFFER 
AND RETURN IT TO THE CALLER ON THE STACK. AFTER THE BYTE HAS 
BEEN FETCHED, THE NEXT BYTE ADDRESS IS INCREMENTED. 
INPUTS: 
R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS. 
OUTPUTS: 
THE NEXT BYTE IS FETCHED FROMT HE USER BUFFER AND RETURNED 
TO THE CALLER ON THE STACK. THE NEXT BYTE ADDRESS IS 
INCREMENTED. 


ALL REGISTERS ARE PRESERVED ACROSS CALL. 


a) ™@ =@ BH WH WH WH =e 28 WE =@ ye UO we BD WS ™e ag WD 


SERVICE CALLS 


SGTPKT 
SGSPKT 


7.5.12 Get Packet 


Get Packet and Get Special Packet are in the file IOSUB. The 
recommended way to use S$GTPKT is to use the GTPKTS macro call defined 
in Section Section 4.3. Usage of SGSPKT is described briefly in 
Section 1.4.3. 
Calling Sequences: 

CALL SGTPKT 


Or 


CALL SGSPKT 


Descriptions: 


es 


**_-SGTPKT-GET I/O PACKET FROM REQUEST QUEUE 
**_SGSPKT-GET SELECTIVE I/O PACKET FROM REQUEST QUEUE 


THIS ROUTINE IS CALLED BY DEVICE DRIVERS TO DEQUEUE THE NEXT I/O 
REQUEST TO PROCESS. IF THE DEVICE CONTROLLER IS BUSY, THEN A 
CARRY SET INDICATION IS RETURNED TO THE CALLER. ELSE AN ATTEMPT 
IS MADE TO DEQUEUE THE NEXT REQUEST FROM THE CONTROLLER QUEUE. 
IF NO REQUEST CAN BE DEQUEUED, THEN A CARRY SET INDICATION IS 
RETURNED TO THE CALLER. ELSE THE CONTROLLER IS SET BUSY AND A 
CARRY CLEAR INDICATION IS RETURNED TO THE CALLER. 


IF QUEUE OPTIMIZATION IS SUPPORTED AND ENABLED FOR THE DEVICE 
THE APROPRIATE PACKET FOR THE CURRENT OPTIMIZATION ALGORITHM 

IS RETURNED. THREE ALGORITHMS ARE SUPPORTED: NEAREST CYLINDER, 
ELEVATOR, AND C-SCAN. ALL THREE ALGORITHMS INCORPORATE A 
FAIRNESS COUNT. IF THE FIRST PACKET ON THE LIST IS PASSED OVER 
MORE THAN "FCOUNT" TIMES, IT IS DONE IMMEDIATELY. 


THE ALTERNATE ENTRY POINT S$GSPKT IS INTENDED FOR USE BY DRIVERS 
WHICH SUPPORT PARALLEL OPERATIONS ON A SINGLE UNIT, A COMMON 
EXAMPLE BEING FULL DUPLEX. SUCH DRIVERS ARE EXPECTED TO LOOK TO 
THE SYSTEM AS IF THEY ARE ALWAYS FREE, WHILE MAINTAINING THE 
STATUS OF ALL PARALLEL OPERATIONS INTERNALLY WITHIN THEIR OWN 
DEVICE DATA STRUCTURES. PARALLELISM IS ACCOMPLISHED BY HANDLING 
DRIVER-DEFINED CLASSES OF I/O FUNCTION CODES IN PARALLEL WITH 
EACH OTHER. FOR EXAMPLE A FULL-DUPLEX DRIVER WOULD HANDLE INPUT 
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SERVICE CALLS 


REQUESTS IN PARALLEL WITH OUTPUT REQUESTS. A DRIVER CALLS S$GSPKT 
WHEN IT WANTS TO DEQUEUE A PACKET WHOSE I/O FUNCTION CODE BELONGS 
CERTAIN CLASS. WHICH FUNCTIONS QUALIFY IS DETERMINED BY AN 
ACCEPTANCE ROUTINE IN THE DRIVER WHOSE ADDRESS IS PASSED TO SGSPK 


TO A 


IN R2. 


THE ACCEPTANCE ROUTINE IS CALLED BY SGSPKT EACH TIME A 


PACKET IS FOUND IN THE QUEUE WHICH IS ELIGIBLE TO BE DEQUEUED. 
THE ACCEPTANCE ROUTINE IS THEN EXPECTED TO TAKE ONE OF THE 
FOLLOWING THREE ACTIONS: 


1. 


3.6 


RETURN WITH CARRY CLEAR IF THE PACKET SHOULD BE 
DEQUEUED. IN THIS CASE $GSPKT PROCEEDS AS SGTPKT 
NORMALLY WOULD ON DEQUEUEING THE PACKET. 


RETURN WITH CARRY SET IF THE PACKET SHOULD NOT BE 
DEQUEUED. IN THIS CASE $GSPKT WILL CONTINUE THE 
SCAN OF THE I/O QUEUE. 


ADD THE CONSTANT GSSSPSA TO THE STACK POINTER TO 
ABORT THE SCAN WITH NO FURTHER ACTION. 


THE ACCEPTANCE ROUTINE MUST SAVE AND RESTORE ANY REGISTERS WHICH 
IT INTENDS TO MODIFY. WHEN A PACKET IS DEQUEUED VIA S$GSPKT, THE 
FOLLOWING NORMAL S$GTPKT ACTIONS DO NOT OCCUR: 


NOTE : 


INPUTS: 


FILLING IN OF U.BUF, U.BUF+2 AND U.CNT. THESE 
FIELDS ARE AVAILABLE FOR DRIVER-SPECIFIC USE. 


BUSYING OF UCB AND SCB. 


EXECUTION OF SCFORK TO GET TO PROPER PROCESSOR 
(MULTI-~PROCESSOR SYSTEMS). 


SGSPKT MAY NOT BE USED BY A DRIVER WHICH SUPPORTS 
QUEUE OPTIMIZATION. 


R2=ADDRESS OF DRIVER'S ACCEPTANCE ROUTINE (IF CALL AT 
SGSPKT). 
R5=ADDRESS OF THE UCB OF THE CONTROLLER TO GET A PACKET 


FOR. 


OUTPUTS: 


C=l1 IF CONTROLLER IS BUSY OR NO REQUEST CAN BE DEQUEUED. 
C=0 IF A REQUEST WAS SUCCESSFULLY DEQUEUED. 


R1=ADDRESS OF THE I/O PACKET. 
R2=PHYSICAL UNIT NUMBER. 

R3=CONTROLLER INDEX. 

R4=ADDRESS OF THE STATUS CONTROL BLOCK. 


7-30 


@™e Be BG BWO 


SERVICE CALLS 


R5=ADDRESS OF THE UNIT CONTROL BLOCK. 


NOTE: R4 AND R5 ARE DESTROYED BY THIS ROUTINE. 


SERVICE CALLS 


SGTWRD 


7.5.13 Get Word 


Get Word is in the file BFCTL. It manipulates words U.BUF and U.BUF+2 
in the UCB. 


Calling Sequence: 
CALL SGTWRD 


Description: 


af 


**—-SGTWRD-GET NEXT WORD FROM USER BUFFER 
THIS ROUTINE IS CALLED TO GET THE NEXT WORD FROM THE USER BUFFER 
AND RETURN IT TO THE CALLER ON THE STACK. AFTER THE WORD HAS 
BEEN FETCHED, THE NEXT WORD ADDRESS IS CALCULATED. 
INPUTS: 
R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS. 
OUTPUTS: 
THE NEXT WORD IS FETCHED FROM THE USER BUFFER AND RETURNED 
TO THE CALLER ON THE STACK. THE NEXT WORD ADDRESS IS 
CALCULATED. 


ALL REGISTERS ARE PRESERVED ACROSS CALL. 
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SERVICE CALLS 


SINIBF 


7.5.14 Initiate I/O Buffering 
This routine is in the file IOSUB. 
Calling Sequence: 

CALL SINIBF 


Description: 


-- 


**-SINIBF-INITIATE I/O BUFFERING 
THIS ROUTINE INITIATES I/O BUFFERING BY DOING THE FOLLOWING: 
1. DECREMENT THE TASK'S I/O COUNT. 
2. INCREMENT THE TASK'S BUFFERED I/O COUNT 
3. INITIATE CHECKPOINTING IF A REQUEST IS PENDING 
INPUTS: 
R3=ADDRESS OF I/O PACKET FOR I/O REQUEST. 
OUTPUTS: 


R3 IS PRESERVED. 
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SERVICE CALLS 


SINTXT 


T4615 Interrupt Exit 
Interrupt Exit is in the file SYSXT. 
Calling Sequence: 

JMP SINTXT 


Description: 


+ 


**_-SINTXT-INTERRUPT EXIT 
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THIS ROUTINE MAY BE CALLED VIA A JMP TO EXIT FROM AN INTERRUPT 
INPUTS: 

0(SP)=INTERRUPT SAVE RETURN ADDRESS. 
OUTPUTS: 


A RETURN TO INTERRUPT SAVE IS EXECUTED. 
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SERVICE CALLS 


SIOALT/SIODON 


7.5.16 I/O Done Alternate Entry and I/O Done 
These routines are in the file IOSUB. 
Calling Sequences: 

CALL SIOALT 

CALL $ IODON 


Description: 


ofe 


**-SIOALT-I/O DONE (ALTERNATE ENTRY) 
**-STODON-I/O DONE 


THIS ROUTINE IS CALLED BY DEVICE DRIVERS AT THE COMPLETION OF AN 
I/O REQUEST TO DO FINAL PROCESSING. THE UNIT AND CONTROLLER ARE 
SET IDLE AND SIOFIN IS ENTERED TO FINISH THE PROCESSING. 


ORO, 
er 


INPUTS: 


RO=FIRST I/O STATUS WORD. 
R1=SECOND I/O STATUS WORD. 


R2=STARTING AND FINAL ERROR RETRY COUNTS IF ERROR LOGGING 
DEVICE. 


R5=ADDRESS OF THE UNIT CONTROL BLOCK OF THE UNIT BEING 
COMPLETED. 
(SP)=RETURN ADDRESS TO DRIVER'S CALLER. 


NOTE: IF ENTRY IS AT SIOALT, THEN R1 IS CLEAR TO SIGNIFY 
THAT THE SECOND STATUS WORD IS .ZERO. 


OUTPUTS * 
THE UNIT AND CONTROLLER ARE SET IDLE. 


R3=ADDRESS OF THE CURRENT I/O PACKET. 
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Notes: 


1. R4 is destroyed when either of these routines is called. The 
routines call SIOFIN, which destroys R4. 


SERVICE CALLS 


SIOFIN 


7.5.17 I/O Finish 


I/O Finish is in the file IOSUB. Most drivers do not call I/O Finish, 
but you should be aware that this routine is executed when a driver 
calls S$IOALT or S$IODON. A driver that references an I/O packet before 
it is queued (bit UC.QUE set-~-see Section 8.1 for an example) calls 
I/O Finish if the driver finds an error while preprocessing the I/O 
packet. 


Calling Sequence: 
CALL SIOFIN 


Description: 


+ 


**-STOFIN-I/O FINISH 


THIS ROUTINE IS CALLED TO FINISH I/O PROCESSING IN CASES WHERE 
THE UNIT AND CONTROLLER ARE NOT TO BE DECLARED IDLE. IF THE TASK 
WHICH ISSUED THE I/O HAS HAD A RECENT MAPPING CHANGE WHICH MAY 
HAVE UNMAPPED ITS I/O STATUS BLOCK, THE I/O PACKET IS QUEUED TO 
THE FRONT OF ITS AST QUEUE TO BE COMPLETED LATER IN $FINBF BY 
CALLING S$IOFIN AGAIN. 


INPUTS: 
RO=FIRST I/O STATUS WORD. 


R1=SECOND I/O STATUS WORD. 
R3=ADDRESS OF THE I/O REQUEST PACKET. 
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OUTPUTS: 
THE FOLLOWING ACTIONS ARE PERFORMED 


1-THE FINAL I/O STATUS VALUES ARE STORED IN THE I/O 
STATUS BLOCK IF ONE WAS SPECIFIED. 


2-ALL ASSOCIATED I/O COUNTS ARE DECREMENTED AND TS.RDN IS 
CLEARED IN CASE THE TASK WAS BLOCKED FOR I/O RUNDOWN. 
T3.MPC IS CLEARED IF THE TASK I/O COUNT GOES TO ZERO TO 
INDICATE THAT THE I/O COUNT WENT TO ZERO AFTER A 
MAPPING CHANGE. 


3-IF ~TS.CKR' IS SET, THEN IT IS CLEARED AND 
CHECKPOINTING OF THE TASK IS INITIATED. 
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SERVICE CALLS 


4-IF AN AST SERVICE ROUTINE WAS SPECIFIED, THEN AN AST IS 
QUEUED FOR THE TASK, ELSE THE I/O PACKET IS DEALLOCATED. 


5-A SIGNIFICANT EVENT OR EQUIVALENT IS DECLARED. 


NOTE: R4 IS DESTROYED BY THIS ROUTINE. 


SERVICE CALLS 


SPTBYT 


7.5.18 Put Byte 


Put Byte is in the file BFCTL. Put Byte manipulates words U.BUF and 
U.BUF+2 in the UCB. 


Calling Sequence: 
CALL SPTBYT 


Description: 


-- 


**-SPTBYT-PUT NEXT BYTE IN USER BUFFER 


THIS ROUTINE IS CALLED TO PUT A BYTE IN THE NEXT LOCATION IN THE 
USER BUFFER. AFTER THE BYTE HAS BEEN STORED, THE NEXT BYTE 
ADDRESS IS INCREMENTED. 


INPUTS: 


R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS. 
2(SP)-BYTE TO BE STORED IN THE NEXT LOCATION OF THE USER 
BUFFER. 


OUTPUTS: 


THE BYTE IS STORED IN THE USER BUFFER AND REMOVED FROM THE 
STACK. 


THE NEXT BYTE ADDRESS IS INCREMENTED. 


ALL REGISTERS ARE PRESERVED ACROSS CALL. 
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SERVICE CALLS 


SPTWRD 


7.5.19 Put Word 


Put Word is in the file BFCTL. It manipulates words U.BUF and U.BUF+2 
in the UCB. 


Calling Sequence: 
CALL SPTWRD 


Description: 


-- 


**-—SPTWRD-PUT NEXT WORD IN USER BUFFER 


THIS ROUTINE IS CALLED TO PUT A WORD IN THE NEXT LOCATION IN 
THE USER BUFFER. AFTER THE WORD HAS BEEN STORED, THE NEXT WORD 
ADDRESS IS CALCULATED. . 


INPUTS: 


RS5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS. 
2(SP)=WORD TO BE STORED IN THE NEXT LOCATION OF THE 
BUFFER. 


OUTPUTS: 


THE WORD IS STORED IN THE USER BUFFER AND REMOVED FROM THE 
STACK. THE NEXT WORD ADDRESS IS CALCULATED. 


ALL REGISTERS ARE PRESERVED ACROSS CALL. 
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SERVICE CALLS 


SQINSP 


7.5.20 Queue Insertion by Priority 

This routine is in the file QUEUE. A driver may call SQINSP to insert 
into the I/O queue an I/O packet that the Executive has not already 
placed in the queue. Queue Insertion by Priority is used only by 
drivers setting UC.QUE in U.CTL. See Section 8.1 for an example. 
Calling Sequence: 


CALL SOINSP 


Descriptions: 


ole 


**_SOINSP-QUEUE INSERTION BY PRIORITY 

THIS ROUTINE IS CALLED TO INSERT. AN ENTRY IN A PRIORITY ORDERED 
LIST. THE LIST IS SEARCHED UNTIL AN ENTRY IS FOUND THAT HAS A 
LOWER PRIORITY OR THE END OF THE LIST IS REACHED. THE NEW ENTRY 
IS THEN LINKED INTO THE LIST AT THE APPROPRIATE POINT. 

INPUTS: 


RO=ADDRESS OF THE TWO WORD LISTHEAD. 
RI=ADDRESS OF THE ENTRY TO BE INSERTED. 


OUTPUTS : 
THE ENTRY IS LINKED INTO THE LIST BY PRIORITY. 


RO AND RI ARE PRESERVED ACROSS CALL. 


=O2@ See WH WE WH VWE WH WH WH WH WH WH WH WH WH WH WH WH WY 


SERVICE CALLS 


SRELOC 


7.5e-2l1 Relocate 


Relocate is in the file MEMAP. A driver may call SRELOC to relocate a 
task virtual address while the task is the current task. Relocate is 
normally used only by drivers setting UC.QUE in U.CTL. See Section 
8.1 for an example. 
Calling Sequence: 

CALL S$RELOC 


Description: 


ao 


**~SRELOC-RELOCATE USER VIRTUAL ADDRESS 
THIS ROUTINE IS CALLED TO TRANSFORM A 16-BIT USER VIRTUAL 
ADDRESS INTO A RELOCATION BIAS AND DISPLACEMENT IN BLOCK 
RELATIVE TO APR6. 
INPUTS: 

RO=USER VIRTUAL ADDRESS TO RELOCATE. 
OUTPUTS: 


R1=RELOCATION BIAS TO BE LOADED INTO PAR6. 
R2=DISPLACEMENT IN BLOCK PLUS 140000 (PAR6 BIAS). 


RO AND R3 ARE PRESERVED ACROSS CALL. 
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SERVICE CALLS 


SREQUE 
SREQUI1 


7.5.22 Queue Kernel AST to Task 
This routine is in module IOSUB. 
Calling Sequence: 
CALL SREQUE 
or 
CALL SREQUI1 
Descriptions: 
7+ | 
e **_.S REQUE-REQUEUEF A REGION LOAD AST TO A TASK AST. 
e**_SREQUI-REQUEUE A REGION LOAD AST TO A TASK AST (ALTERNATE 
ENTRY). 
THESE ROUTINES ARE USED TO QUEUE A TASK KERNEL AST WHICH HAS 


BEEN USED AS A REGION LOAD AST BACK AS A TASK AST. THE BUFFERED 
I/O COUNT OF THE TASK IS DECREMENTED IF ENTRY AT SREQUE. 


INPUTS: 
RO=TCB ADDRESS OF ASSOCIATED TASK 
R3=ADDRESS OF PACKET TO BE QUEUED 


OUTPUTS: 
NONE. 
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SERVICE CALLS 


STSPAR 


7.5.23 Test if Partition Memory Resident for Kernel AST 
This routine is in file REQSB. 
Calling Sequence: 
CALL STSPAR 
Description: 
**-STSPAR-TEST IF PARTITION IS IN MEMORY FOR KERNEL AST 


THIS ROUTINE IS CALLED TO CHECK A REGION FOR MEMEORY RESIDENCE 
TO DETERMINE IF IT IS SAFE TO SERVICE A KERNEL AST (E.G. COPY 
A BUFFER) INTO THE REGION. IF THE REGION IS CHECKPOINTED OR 
CURRENTLY BEING CHECKPOINTED, THEN A REGION LOAD AST IS QUEUED 
AND THE REGION IS ACCESSED ON THE TASKS BEHALF. 


INPUTS: 
RO=ADDRESS OF PACKET PEING PROCESSED 
R1=PCB ADDRESS OF REGION 
R5=TCB ADDRESS OF ASSOCIATED TASK 


OUTPUTS : 
C=0 IF REGION IS MEMORY RESIDENT | 
C=] IF REGION IS NON-RESIDENT. IN THIS CASE THE REGION AST 
HAS BEEN QUEUED, ETC. 
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SERVICE CALLS 


STSTBF 


7.5.24 Test for I/O Buffering 
This routine is in file IOSUB. 
Calling Sequence: 

CALL STSTBF 


Descriptions: 


+ 


**-STSTBF-TEST IF I/O BUFFERING CAN BE INITIATED 
THIS ROUTINE DETERMINES IF A GIVEN I/O REQUEST IS ELIGIBLE FOR 
I/O BUFFERING, AND IF SO IT STORES THE PCB ADDRESS OF THE REGION 
INTO WHICH THE TRANSFER IS TO OCCUR IN I.PRM+16 OF THE I/O 
PACKET. 
INPUTS: 

R3=ADDRESS OF I/O PACKET FOR I/O REQUEST 
OUTPUTS : 

R3 IS PRESERVED. 

C=0 IF I/O BUFFERING CAN BE INITIATED. 


C=1 IF I/O BUFFERING CAN NOT BE INITIATED. 
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7.6 ADDING PHYSICAL MEMORY TO THE P/OS CONFIGURATION 


Option modules that contain additional (possibly special purpose) 
memory, can allow it to be accessible to the system and applications 
by calling the privileged executive subroutine SSTPAR in the 
distributed PRVLIB.OLB object library. It must be called at system 
state. In order to access the executive vector table, kernel APR6 is 
used. Therefore, the routine must be mapped through APR5 when called. 
This routine is system version independent. Note that system. state 
may be entered without the necessity of being bound to the system 
version, by using the SWSTS directive. 


ADDING PHYSICAL MEMORY TO THE P/OS CONFIGURATION 


If the additional memory is general purpose and there are _ no 
restrictions on its use, it may be added to the "GEN" main partition. 
Tasks, commons, and most PLAS regions are allocated from GEN _ on 
demand. If the memory is to be used for a dedicated purpose, a main 
partition of the name "SPARsx" can be specified - where "s" is’ the 
logical slot number corresponding to the slot in which the board is 
located and "x" is any legal RAD50 character. This convention reduces 
the likelihood of a collision on the partition name. The partition 
name must be unique among all of the (region and partition) names in 
the system. Dedicated memory can be accessed, specifying the given 
Main partition name in the creation of a PLAS region subpartition. 
Memory is allocated from the main partition, using a "first fit" 
algorithm unless the region is being fixed. If it is, the region is 
loaded. high. If the region is already in memory, an attempt is made 
to checkpoint it so that it can be loaded high. Once additional 


memory has been added to the system configuration, it can not be 
removed. 


The calling interface to $STPAR is as follows: 


of 


SSTPAR -- add additional memory to system configuration 
Inputs: 
Rl = base address modulus-1l (modulus granularity = 64 bytes) 


for example, if a base address modulus of 128KB was 
required, this parameter would be 3777(8). 


required PCBs 


; R2 = size of memory to add (granularity = 32 Kbytes) 

: R3 = name of main partition 

; (must be unique if not "GEN ") 

; (if the partition name "GEN " is specified, the 
; additional memory will be appended to to this 

; main partition.) 

; Output: 

? Cc=0, 

; R2 = base address of the region (granularity = 64 bytes) 
7 C=l1, 

; R2 = 0 partition name already exists 

; R2 = 2 insufficient space in available physical 

: address space 

; R3 = 4 insufficient primary pool space to allocate 


EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS 


7.7/7 EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS 


In order to allow greater system version independence for privileged 
tasks and device drivers, a simple vectoring scheme has_ been 
implemented in P/OS version 2.0. 


Prior to version 2.0, a privileged task was needed to link with the 
system’s symbol table file to resolve references to various executive 
routine and data structure addresses. Since these addresses changed 
with every system version, it was necessary to rebuild the component 
for each version of the system. By creating a set of absolute 
addresses which point to various tables, a privileged component can 
resolve the necessary addresses at runtime. 


While it cannot be guaranteed, DIGITAL will attempt to maintain upward 
compatibility of the P/OS executive data structures and routines. 
Therefore, the tables provided below are on a "USE AT YOUR OWN’ RISK" 
basis. In particular, the data structures can and will change in the 
next version of P/OS. Each vectored executive routine is stamped with 
an IDENT which may be used as a validity check during initialization. 


There are three absolute pointers in the P/OS executive. The first 
points to the executive module LOWCR, the second to SYSCM and the 
third pointer consists of a bias and a displacement offset by 140000, 
which is used to map the executive routine vector table. In addition, 
the SBTMSK bit table has been moved to an absolute location. 


yea are | Pointer Location and Format 


The vector table pointers are located in the following absolute 
locations: 


Symbolic Name Address Description 

SBTMSK 1002 bitmask table 

SVECLC 1042 address of SSTACK 

SVECSC 1044 address of SCMBEG 

SVECVT 1046 bias of vector table 
1050 displacement+140000(8) 


The executive routine vector table's format is: 


» WORD number of vectors in table 
SVECVT--> . WORD SXXX,reserved, IDENT ;entry point 0 
» WORD SXXX, reserved, IDENT ;entry point 1 


where, 


Vele2 


The following example illustrates one method of binding an 
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SXXX is the address of the executive routine 

reserved is not currently used though may be used in 
the future to contain a bias. 

IDENT 


is a value associated with the particular 
routine which is incremented when the routine 
changes in a non upward compatible manner. 


Referencing LOWCR and SYSCM Data Structures 


executive 


data structure reference at runtime. 


MYTCB: 


ARGBLK: 


BUF: 


FORMAT : 


r= S=eage =E@ BE BO 


NIT: 


TYPIT: 


eMCALL 
»PSECT 
«WORD 


- BLKW 
» BLKB 


eASCIZ 
eEVEN 


ePSECT 


MOV 
CALL 
ADD 
MOV 
MOV 
MOV 
RETURN 


MOV 
MOV 
MOV 
CALL 
QOIOWSS 
EXITSS 


» END 


OIOWSS ,EXITSS ssystem macros 


DATA,D 


STKTCB-SSTACK -form offset from base of 
*LOWCR to STKTCB (absolute) 
2 sargument block/taskname buf 


80. ;Output buffer 


/My name is %2R and I got it the hard way/ 


CODE, I 


This task prints its taskname and exits. Could have been 
done simpler using GTSKS however, the example is one 
technique to resolve the symbol STKTCB in LOWCR. 


#ARGBLK,R2 spoint at taskname buffer 
SSWSTK,TYPIT senter system state 
@#SVECLC,MYTCB +;resolve address of STKTCB 
MYTCB;R5 eget current task's TCB addr 


T.NAM(R5),(R2)+ s;get my task name 
T.NAM+2(R5) ,(R2) 
return to user state (which 
srestores registers) 


#BUF ,RO spoint at output buffer 
#FORMAT,R1 spoint to format string 
#ARGBLK+2,R2 spoint to argument block 
SEDMSG -format output 


#TO.WVB,#5,#5,,,,<#BUF,R1,#40> ;output to msg 
exit 


INIT 
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72.7.3 Referencing Executive Routines 


The following example subroutine illustrates one method of referencing 
a vectored executive routine. 


ePSECT DATA,D 


TKTCB: STKTCB-SSTACK -offset in LOWCR to STKTCB 
SETFG: SETFGS ;entry point symbols defined 
* in PRVLIB 
e WORD 1 sversion number at time routine 
* written 
HIVEC: » WORD SETFGS /<3*2> ;each entry point consists of 3 
- words. 


~PSECT CODE,I 


; This subroutine sets the this task's local event flag the 
; hard way. (It illustrates the vectoring as opposed to a 
; SETFS replacement.) 
SETF: CLR SERROR 
CALL SSWSTK , 20$ -enter system state 
ADD @#VECLC,TKTCB sresolve reference to S$STKTCB 
MOV @#KISAR6,-(SP) ;save current APR6 mapping 
MOV @#SVECVT,@#KISAR6 ;map vector table 
MOV @#VECVT+2,R1 ;point to vector table 
CMP HIVEC,-2(R1) does vector table describe 
sentry point? 
BHI 108 -if hi vectoring error has 
;occurred 
ADD SETFG,R1 ;point to entry point in table 
CMP SETFG+2,4(R1) ssame IDENT? 
BNE 10$ -if ne no, routine has changed 
MOV (R1),R1 resolve reference to SSETFG 
MOV #1,R0 ;specify event flag to set 
MOV @TKTCB,R5 sget this task’s TCB address 
CALL (R1) eset a this task’s local event 
sflag l 
BR 15$ 
108: DEC SERROR 
15S: MOV (SP)+,@#KISAR6 
208: RETURN 


7.7.4 Executive Routine Vector Table 


~TITLE EXEVEC 
~IDENT /01.00/ 


WI NO 


=e 


we B@@ BE WE BO BE BS WH BQ VZWE WH WH WS 


~e @™=@ ~@@O @2e@ =e BO 
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COPYRIGHT (c) 1984 BY DIGITAL EQUIPMENT CORPORATION. 
ALL RIGHTS RESERVED. 


THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED 
OR COPIED ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE. 


EXEVEC -- THIS MODULE DEFINES SELECTED EXECUTIVE ENTRY POINTS 
SO THAT DRIVERS AND PRIVILEGED TASKS MAY BE SYSTEM 

VERSION INDEPENDENT. THERE IS NO IMPLIED GUARANTEE 

THAT THE EACH ENTRY POINT’S INTERFACE WILL REMAIN STABLE 
THOUGH THERE IS SOME INTEREST IN KEEPING THEM UPWARD 
COMPATIBLE IF POSSIBLE. AN IDENT HAS BEEN PROVIDED 

WHICH CAN BE USED TO IDENTIFY THE VERSION OF THE 

REFERENCED ROUTINE. 


SALOCB -- ALLOCATE CORE BLOCK 


ROUTINE VERSION NUMBER = 1 MODULE NAME = CORAL 
VECTOR TABLE OFFSET NAME = ALOCBS OFFSET VALUE= 0 


SDEACB -- DEALLOC. CORE BLK 


ROUTINE VERSION NUMBER = 1 MODULE NAME = CORAL 
VECTOR TABLE OFFSET NAME DEACBS OFFSET VALUE= 6 


SALOC1] -- ALLOC. CORE BLK (SPECIFIABLE LSTHD) 


ROUTINE VERSION NUMBER 
VECTOR TABLE OFFSET NAME 


1 MODULE NAME = CORAL 
ALOC1S OFFSET VALUE= 14 


SDEAC1] -- DEALLOC. CORE BLK (SPECIFIABLE LSTHD) 


ROUTINE VERSION NUMBER 
VECTOR TABLE OFFSET NAME 


1 MODULE NAME = CORAL 
DEAC1S OFFSET VALUE= 22 


SALCLK -- ALLOC. CLOCK QUEUE CORE BLK 


we BG we WE WH ~BWGS WOH WH VE BSH BWE WH BH WH WS me ~™e BZE WE WOH VBS BSH WS BWE WS WHE WE WH WHE WH VW WS 


ROUTINE VERSION NUMBER = ] MODULE NAME = CORAL 
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VECTOR TABLE OFFSET NAME 


= ALCLKS OFFSET VALUE= 30 


SDECLK -- DEALLOC. CLOCK QUEUE CORE BLK 


ROUTINE VERSION NUMBER 
VECTOR TABLE OFFSET NAME 


SALPKT -- ALLOC. I/O PACK 


ROUTINE VERSION NUMBER 
VECTOR TABLE OFFSET NAME 


SDEPKT -- DEALLOC. I/O PA 


ROUTINE VERSION NUMBER 
VECTOR TABLE OFFSET NAME 


SALSEC -- ALLOC. SECONDA 


ROUTINE VERSION NUMBER 
VECTOR TABLE OFFSET NAME 


= ] MODULE NAME = CORAL 
= DECLKS OFFSET VALUE= 36 


ET 


1 MODULE NAME = CORAL 
ALPKTS OFFSET VALUE= 44 


CKET 


= ] MODULE NAME = CORAL 
= DEPKTS OFFSET VALUE= 52 


RY POOL CORE BLK 


= ] MODULE NAME = CORAL 
= ALSECS OFFSET VALUE= 60 


SDESEC -- DEALLOC. SECONDARY POOL CORE BLK 


ROUTINE VERSION NUMBER 
VECTOR TABLE OFFSET NAME 


SGTBYT -- GET NEXT BYTE F 


ROUTINE VERSION NUMBER 
VECTOR TABLE OFFSET NAME 


= ] MODULE NAME = CORAL 
= DESECS OFFSET VALUE= 66 


ROM USER BUFFER 


= ] MODULE NAME = BFCTL 
= GTBYTS OFFSET VALUE= 74 


SPTBYT -- PUT NEXT BYTE IN USER BUFFER 


ROUTINE VERSION NUMBER 
{VECTOR TABLE OFFSET NAME 


= ] MODULE NAME = BFCTL 
= PTBYTS OFFSET VALUE= 102 


we *ZS ZH WH WH WH WH WH WE AWS WH WS BVH RH WH WE BS WE WE BWHE WH WH VQ VS WHE WH WH WS =e ™@@ 
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SGTWRD -- GET NEXT WORD FROM USER BUFFER 


ROUTINE VERSION NUMBER = 1 MODULE NAME = BFCTL 
VECTOR TABLE OFFSET NAME = GTWRDS OFFSET VALUE= 110 


SPTWRD -- PUT NEXT WORD IN USER BUFFER 


ROUTINE VERSION NUMBER = 1 MODULE NAME = BFCTL 
VECTOR TABLE OFFSET NAME = PTWRDS OFFSET VALUE= 116 


SBLXIO -- MOVE BLOCK OF DATA 


ROUTINE VERSION NUMBER = 1 MODULE NAME = BFCTL 
VECTOR TABLE OFFSET NAME = BLXIOS OFFSET VALUE= 124 


SCLINS -- CLOCK QUEUE INSERTION 


ROUTINE VERSION NUMBER = ] MODULE NAME = QUEUE 
VECTOR TABLE OFFSET NAME = CLINSS OFFSET VALUE= 132 


SCLRMV -- CLOCK QUEUE REMOVAL 


ROUTINE VERSION NUMBER = 1 MODULE NAME = QUEUE 
VECTOR TABLE OFFSET NAME = CLRMVS OFFSET VALUE= 140 


SQINSF -- QUEUE INSERTION AT END OF LIST 


ROUTINE VERSION NUMBER = ] MODULE NAME = QUEUE 
VECTOR TABLE OFFSET NAME = QINSFS OFFSET VALUE= 146 


SOINSP -- QUEUE INSERTION BY PRIORITY 


ROUTINE VERSION NUMBER = 1 MODULE NAME = QUEUE 
VECTOR TABLE OFFSET NAME = QINSPS OFFSET VALUE= 154 


=e ~@@ =6 BE BF WH WH WH WH WS WH WH WH WH BWE BWH BVH WH BVH WH VE WH WH WE WE WE WS 
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SQINSB -- QUEUE INSERTION AT BEGINNING 


ROUTINE VERSION NUMBER = 1 MODULE NAME = QUEUE 
VECTOR TABLE OFFSET NAME = QINSBS OFFSET VALUE= 162 


SQRMVA -- QUEUE REMOVAL BY BLOCK ADDRESS 


ROUTINE VERSION NUMBER = 1 MODULE NAME = QUEUE 
VECTOR TABLE OFFSET NAME = QRMVAS OFFSET VALUE= 170 


SQORMVT -- QUEUE REMOVAL BY TCB ADDRESS 


ROUTINE VERSION NUMBER = 1 MODULE NAME = QUEUE 
VECTOR TABLE OFFSET NAME = QRMVTS OFFSET VALUE= 176 


SOSPIB -- QUEUE INSERTION (SEC. POOL) AT BEG. 


ROUTINE VERSION NUMBER = 1 MODULE NAME = QUEUE 
VECTOR TABLE OFFSET NAME = QSPIBS OFFSET VALUE= 204 


SQOSPIF -- QUEUE INSERTION (SEC. POOL) AT END. 


ROUTINE VERSION NUMBER = ] MODULE NAME = QUEUE 
VECTOR TABLE OFFSET NAME = QSPIFS OFFSET VALUE= 212 


SOSPRF -- QUEUE REMOVAL (SEC. POOL) FROM FRONT 


ROUTINE VERSION NUMBER = 1 MODULE NAME = QUEUE 
VECTOR TABLE OFFSET NAME = QSPRFS OFFSET VALUE= 220 


SOSPIP -- QUEUE INSERTION (SEC. POOL) BY PRI. 


ROUTINE VERSION NUMBER = 1 MODULE NAME = QUEUE 
VECTOR TABLE OFFSET NAME = QSPIPS OFFSET VALUE= 226 


SGTSPK -- QUEUE REMOVAL (SEC. POOL) BY BLK ADR 


~e ws % @ wee WG VWS ~Oe WE me 2e@ Be te w~=e BE ~ @ =e Be WE =O BG BS ~e@ BZG WG ~™e 
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ROUTINE VERSION NUMBER . = 1 MODULE NAME = QUEUE 
VECTOR TABLE OFFSET NAME = GTSPKS OFFSET VALUE= 234 


SACHCK -- ADDRESS CHECK WORD ALIGNED (NO I/O CNTS) 


ROUTINE VERSION NUMBER = 1 MODULE NAME = EXESB 
VECTOR TABLE OFFSET NAME = ACHCKS OFFSET VALUE= 242 


SACHKB -- ADDRESS CHECK BYTE ALIGNED (NO I/O CNTS) 


ROUTINE VERSION NUMBER = 1 MODULE NAME = EXESB 
VECTOR TABLE OFFSET NAME = ACHKBS OFFSET VALUE= 250 


SACHRO -- ADDRESS CHECK FOR READONLY ACCESS NO IOC 


ROUTINE VERSION NUMBER = 1 MODULE NAME = EXESB 
VECTOR TABLE OFFSET NAME = ACHROS OFFSET VALUE= 256 


SCKBFW -- CHECK I/O BUFFER FOR READONLY (BYTE) 


ROUTINE VERSION NUMBER = ] MODULE NAME = EXESB 
VECTOR TABLE OFFSET NAME = CKBFWS OFFSET VALUE= 264 


SCKBFB -- CHECK I/O BUFFER FOR READWRITE (BYTE) 


ROUTINE VERSION NUMBER = ] MODULE NAME = EXESB 
VECTOR TABLE OFFSET NAME = CKBFBS OFFSET VALUE= 272 


SCKBFR -- CHECK I/O BUFFER FOR READWRITE (WORD) 


ROUTINE VERSION NUMBER = ] MODULE NAME = EXESB 
VECTOR TABLE OFFSET NAME = CKBFRS OFFSET VALUE= 300 


SCEFIG -- CONVERT EVENT FLAG AND LOCK FOR I/O 


ROUTINE VERSION NUMBER = 1] MODULE NAME = EXESB 
VECTOR TABLE OFFSET NAME = CEFIGS. OFFSET VALUE= 306 
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SCEFI -- CONVERT EVENT FLAG FOR I/O 


ROUTINE VERSION NUMBER = 1 MODULE NAME = EXESB 
VECTOR TABLE OFFSET NAME = CEFIS OFFSET VALUE= 314 


SCVDVN -- CONVERT DEV NAM AND LOGICAL UNIT TO UCB 


ROUTINE VERSION NUMBER = 1 MODULE NAME = EXESB 
VECTOR TABLE OFFSET NAME = CVDVNS OFFSET VALUE= 322 


SMPLNE -- MAP LOGICAL UNIT NUMBER 


ROUTINE VERSION NUMBER = 1 MODULE NAME = EXESB 
VECTOR TABLE OFFSET NAME = MPLNES OFFSET VALUE= 330 


SMPLND -- MAP LOGICAL UNIT NUMBER (ALTRN. ENTRYPT) 


ROUTINE VERSION NUMBER = ] MODULE NAME = EXESB 
VECTOR TABLE OFFSET NAME = MPLNDS OFFSET VALUE= 336 


STKWSE -- WAIT FOR SIGNIFICANT EVENT 


ROUTINE VERSION NUMBER = 1 MODULE NAME = EXESB 
VECTOR TABLE OFFSET NAME = TKWSES OFFSET VALUE= 344 


SRELOC -- RELOCATE USER VIRTUAL ADDRESS 


ROUTINE VERSION NUMBER = 1 MODULE NAME = MEMAP 
VECTOR TABLE OFFSET NAME = RELOCS OFFSET VALUE= 352 


SRELOM -- RELOCATE AND MAP USER VIRTUAL ADDRESS 


ROUTINE VERSION NUMBER = 1 MODULE NAME = MEMAP 
VECTOR TABLE OFFSET NAME = RELOMS OFFSET VALUE= 360 
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SCVLBN -- CONVERT LOGICAL BLOCK NUMBER TO DISK PARAMS 


ROUTINE VERSION NUMBER = 1 MODULE NAME = MDSUB 
VECTOR TABLE OFFSET NAME = CVLBNS OFFSET VALUE= 366 


SBLKCK -- LOGICAL BLOCK CHECK ROUTINE 


ROUTINE VERSION NUMBER = ] MODULE NAME = MDSUB 
VECTOR TABLE OFFSET NAME = BLKCKS OFFSET VALUE= 374 


SBLKC1 -- LOGICAL BLOCK CHECK ROUTINE ALTRN. ENTRYPT. 


ROUTINE VERSION NUMBER = 1 MODULE NAME = MDSUB 
VECTOR TABLE OFFSET NAME = BLKC1S OFFSET VALUE= 402 


SBLKC2 -- LOGICAL BLOCK CHECK ROUTINE FOR QUEUE OPT 


ROUTINE VERSION NUMBER = 1 MODULE NAME = MDSUB 
VECTOR TABLE OFFSET NAME = BLKC2S OFFSET VALUE= 410 


SROCNC -- REQUEST CONTROLLER FOR CONTROL OPERATION 


ROUTINE VERSION NUMBER = ] MODULE NAME = MDSUB 
VECTOR TABLE OFFSET NAME = ROCNCS OFFSET VALUE= 416 


SROCND -- REQUEST CONTROLLER FOR DATA TRANSFER 


ROUTINE VERSION NUMBER = ] MODULE NAME = MDSUB 
VECTOR TABLE OFFSET NAME = ROCNDS OFFSET VALUE= 424 


SRLCN -- RELEASE CONTROLLER 


ROUTINE VERSION NUMBER = 1 MODULE NAME = MDSUB 
VECTOR TABLE OFFSET NAME = RLCNS OFFSET VALUE= 432 


SVOLVD -- PREPROCESS VOLUME VALID FUNCTION 


1=D2 
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ROUTINE VERSION NUMBER = 1 MODULE NAME = MDSUB 
VECTOR TABLE OFFSET NAME = VOLVDS OFFSET VALUE= 440 


SVOLSC -- VOLUME STATUS CHANGE 


ROUTINE VERSION NUMBER = 1 MODULE NAME = OLRSR 
VECTOR TABLE OFFSET NAME = VOLSCS OFFSET VALUE= 446 


SDECIO -- DECREMENT I/O COUNT VIA ADB 


ROUTINE VERSION NUMBER = 1 MODULE NAME = IOSUB 
VECTOR TABLE OFFSET NAME = DECIOS OFFSET VALUE= 454 


SDECIP -- DECREMENT I/O COUNT PARTITION ONLY 


ROUTINE VERSION NUMBER = 1 MODULE NAME = IOSUB 
VECTOR TABLE OFFSET NAME = DECIPS OFFSET VALUE= 462 


SGTPKT -- GET I/O PACKET FROM REQUEST QUEUE 


ROUTINE VERSION NUMBER = 1 MODULE NAME = IOSUB 
VECTOR TABLE OFFSET NAME = GTPKTS OFFSET VALUE= 470 


SGSPKT -- GET SELECTIVE I/O PACKET FROM REQUEST QUEUE 


ROUTINE VERSION NUMBER = 1 MODULE NAME = IOSUB 
VECTOR TABLE OFFSET NAME = GSPKTS OFFSET VALUE= 476 


STSTBF -- TEST IF I/O BUFFERING SHOULD BE INITIATED 


ROUTINE VERSION NUMBER = 1 MODULE NAME = IOSUB 
VECTOR TABLE OFFSET NAME = TSTBFS OFFSET VALUE= 504 


SINIBF -- INITIATE I/O BUFFERING 


ROUTINE VERSION NUMBER = 1 MODULE NAME = IOSUB 
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VECTOR TABLE OFFSET NAME = INIBFS OFFSET VALUE= 512 


SQUEBF -- QUEUE BUFFERED I/O FOR COMPLETION 


ROUTINE VERSION NUMBER = 1 MODULE NAME = IOSUB 
VECTOR TABLE OFFSET NAME = QUEBFS OFFSET VALUE= 520 


SREQUE -- REQUEUE A REGION LOAD AST TO A TASK AST 


ROUTINE VERSION NUMBER = |] MODULE NAME = IOSUB 
VECTOR TABLE OFFSET NAME = REQUES OFFSET VALUE= 526 


SREQU1 -- REQUEUE A REG LOAD AST (ALTERNATE ENTRYPOINT) 


ROUTINE VERSION NUMBER = 1 MODULE NAME = IOSUB 
VECTOR TABLE OFFSET NAME = REQUIS OFFSET VALUE= 534 


SIOALT -- I/O DONE ALTERNATE ENTRY POINT (ERRORS) 


ROUTINE VERSION NUMBER = ] MODULE NAME = IOSUB 
VECTOR TABLE OFFSET NAME = IOALTS OFFSET VALUE= 542 


SIODON -- I/O DONE 


ROUTINE VERSION NUMBER = ] MODULE NAME = IOSUB 
VECTOR TABLE OFFSET NAME = IODONS OFFSET VALUE= 550 


SIOFIN -- I/O FINISH 


ROUTINE VERSION NUMBER = ] MODULE NAME = IOSUB 
VECTOR TABLE OFFSET NAME = IOFINS OFFSET VALUE= 556 


SDECAL -- DECREMENT ALL I/O COUNTS AND UNBLK TASK 


ROUTINE VERSION NUMBER = ] MODULE NAME = IOSUB 
VECTOR TABLE OFFSET NAME = DECALS OFFSET VALUE= 564 
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SDECBF -- DECREMENT ALL PARTITION I/O CNTS & UNBLK TASK 


ROUTINE VERSION NUMBER = 1 MODULE NAME = IOSUB 
VECTOR TABLE OFFSET NAME DECBF$S OFFSET VALUE= 572 


SIOKIL -- I/O KIL 


ROUTINE VERSION NUMBER = 1 MODULE NAME = IOSUB 
VECTOR TABLE OFFSET NAME IOKILS OFFSET VALUE= 600 


SSCDVT -- SCAN DEVICE TABLES 


ROUTINE VERSION NUMBER = 1 MODULE NAME = IOSUB 
VECTOR TABLE OFFSET NAME = SCDVTS OFFSET VALUE= 606 


SSCDV1 -- SCAN DEVICE TABLES (ALTRN. ENTRYPT) 


ROUTINE VERSION NUMBER = 1 MODULE NAME = IOSUB 
VECTOR TABLE OFFSET NAME = SCDVI1S OFFSET VALUE= 614 


SSRNAM -- SEARCH FOR NAMED PARTITION 


ROUTINE VERSION NUMBER = ] MODULE NAME = PLSUB 
VECTOR TABLE OFFSET NAME = SRNAMS OFFSET VALUE= 622 


SSETCR -- SET CONDITIONAL SCHEDULE REQUEST 


ROUTINE VERSION NUMBER = 1 MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = SETCRS OFFSET VALUE= 630 


SSETRQ -- SET SCHEDULE REQUEST 


ROUTINE VERSION NUMBER = 1] MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = SETROS OFFSET VALUE= 636 
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SSETRT -- SET SCHEDULE REQUEST FOR CURRENT TASK 


ROUTINE VERSION NUMBER = 1 MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = SETRTS OFFSET VALUE= 644 


SSETMG -- SET EVENT FLG & UNLCK W/EVNT FLG MASK 


ROUTINE VERSION NUMBER = 1 MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = SETMGS OFFSET VALUE= 652 


SSETFG -- SET EVENT FLAG AND UNLOCK W/EFN NUMBER 


ROUTINE VERSION NUMBER = 1 MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = SETFGS OFFSET VALUE= 660. 


SDASTT -- DECLARE AST TRAP 


ROUTINE VERSION NUMBER = 1 MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = DASTTS OFFSET VALUE= 666 


SQASTC -- QUEUE AST TO TASK (USED W/CINTS) 


ROUTINE VERSION NUMBER = 1 MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = QASTCS OFFSET VALUE= 674 


SQASTT -- QUEUE AST TO TASK 


ROUTINE VERSION NUMBER = 1] MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = QASTTS OFFSET VALUE= 702 


SSRSTD -- SEARCH SYSTEM TASK DIRECTORY 


ROUTINE VERSION NUMBER = 1 MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = SRSTDS$ OFFSET VALUE= 710 


SSTPCT -- STOP CURRENT TASK 
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ROUTINE VERSION NUMBER = 1 MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME STPCTS OFFSET VALUE= 716 


SSTPTK -- STOP TASK 


ROUTINE VERSION NUMBER = 1 MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME STPTKS OFFSET VALUE= 724 


SNXTSK -- ASSIGN NEXT REGION TO PARTITION 


ROUTINE VERSION NUMBER = 1 MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = NXTSKS OFFSET VALUE= 732 


STSPAR -- TEST IF PARTITION IN MEMORY FOR KERNEL AST 


ROUTINE VERSION NUMBER = 1 MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = TSPARS OFFSET VALUE= 740 


SICHKP -- INITIATE CHECKPOINT 


ROUTINE VERSION NUMBER = 1 MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = ICHKPS OFFSET VALUE= 746 


SEXROP -- EXEC REQUEST WITH QUEUE INSERT BY PRIORITY 


ROUTINE VERSION NUMBER = 1 MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = EXROPS OFFSET VALUE= 754 


SEXROF -- EXEC REQUEST WITH QUEUE INSERT FIFO 


ROUTINE VERSION NUMBER = ] MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = EXROFS OFFSET VALUE= 762 


SEXRON -- EXEC REQUEST WITH NO QUEUE INSERT 


ROUTINE VERSION NUMBER = 1 MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = EXRONS OFFSET VALUE= 770 


7-60 


we BE BWE WH WH WH WE WH WHE WHE WE WH WH BME WH WE WH WS WE WOH WH BWE WH VE WH WO ™=@ BO *®~Q BWH WO 


~™e@ *€@ ~WEe WE WS BE WH ~WH WH VE BVH VH VH WHE WH WS WHE WHE WH WE 


EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS 


SEXROQU -- EXEC REQUEST AND UNSTOP WITH NO INSERT 


ROUTINE VERSION NUMBER = 1 MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = EXRQUS OFFSET VALUE= 776 


SEXROS -- EXEC REQUEST WITH NO SCHEDULE REQUEST 


ROUTINE VERSION NUMBER = 1 MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = EXROSS OFFSET VALUE= 1004 


STSKRT -- TASK REQUEST (DEFAULT UCB) 


ROUTINE VERSION NUMBER = ] MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = TSKRTS OFFSET VALUE= 1012 


STSKRQ -- TASK REQUEST (SPECIFY UCB) 


ROUTINE VERSION NUMBER = ] MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = TSKROS OFFSET VALUE= 1020 


STSKRP -- TASK REQUEST (SPECIFY DEFAULT UIC) 


ROUTINE VERSION NUMBER = ] MODULE NAME = REQSB 
VECTOR TABLE OFFSET NAME = TSKRPS OFFSET VALUE= 1026 


SFORK -- FORK AND CREATE SYSTEM PROCESS 


ROUTINE VERSION NUMBER = 1 MODULE NAME = SYSXT 
VECTOR TABLE OFFSET NAME = FORKS OFFSET VALUE= 1034 


SFORK1 -- FORK AND CREATE SYSTEM PROCESS 


ROUTINE VERSION NUMBER = ] MODULE NAME = SYSXT 
VECTOR TABLE OFFSET NAME = FORKI1S OFFSET VALUE= 1042 


™=6@ =@=6 @B=@ ®~O =@=6 BH B™~S BS WHE WHE WE WH WHO WHE 
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EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS 


SFORKO -- FORK AND CREATE SYSTEM PROCESS 


ROUTINE VERSION NUMBER = 1 MODULE NAME = SYSXT 
VECTOR TABLE OFFSET NAME = FORKOS OFFSET VALUE= 1050 


SFORK2 -- FORK AND CREATE SYSTEM PROCESS USED W/CINTS 


ROUTINE VERSION NUMBER = 1 MODULE NAME = SYSXT 
VECTOR TABLE OFFSET NAME = FORK2S OFFSET VALUE= 1056 


SQFORK -- INSERT FORK BLOCK AT END OF FORK QUEUE 


ROUTINE VERSION NUMBER = 1 MODULE NAME = SYSXT 
VECTOR TABLE OFFSET NAME = QFORKS OFFSET VALUE= 1064 


SNONSI -- NONSENSE INTERRUPT ENTRY POINT 


ROUTINE VERSION NUMBER = 1 MODULE NAME = SYSXT 
VECTOR TABLE OFFSET NAME = NONSIS OFFSET VALUE= 1072 


SDSPKA -- DISPATCH KERNEL AST 


ROUTINE VERSION NUMBER = 1] MODULE NAME = SYSXT 
VECTOR TABLE OFFSET NAME = DSPKAS OFFSET VALUE= 1100 


SSGFIN -- SEGMENT FAULT AND TRAP 4 INTERCEPT ROUTINE 


ROUTINE VERSION NUMBER = 1 MODULE NAME = SYSXT 
VECTOR TABLE OFFSET NAME = SGFINS OFFSET VALUE= 1106 


SNLTMO -- NULL TIMEOUT ROUTINE 


ROUTINE VERSION NUMBER = 1 MODULE NAME = TDSCH 
VECTOR TABLE OFFSET NAME = NLTMOS OFFSET VALUE= 1114 


SMUL -- INTEGER MULTIPLY MAGNITUDE NUMBERS 


1=62 
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EXECUTIVE DATA STRUCTURE AND ROUTINE VECTORS 


ROUTINE VERSION NUMBER = 1] MODULE NAME = UTSUB 

VECTOR TABLE OFFSET NAME = MULS OFFSET VALUE= 1122 
SDIV -- INTEGER DIVIDE MAGNITUDE NUMBERS 

ROUTINE VERSION NUMBER = 1 MODULE NAME = UTSUB 


VECTOR TABLE OFFSET NAME 


SDBDIV -- 


ROUTINE VERSION NUMBER 
VECTOR TABLE OFFSET NAME 


SCAT5 -- CONVERT ASCII TO 


ROUTINE VERSION NUMBER 
VECTOR TABLE OFFSET NAME 


= DIVS OFFSET VALUE= 1130 


DOUBLE PRECISION DIVIDE MAGNITUDE NUMBERS 


= ] MODULE NAME = UTSUB 
= DBDIVS OFFSET VALUE= 1136 


RAD50 


= ] MODULE NAME = UTSUB 
= CAT5S OFFSET VALUE= 1144 


SSAVNR -- SAVE NON VOLATILE REGISTERS 
ROUTINE VERSION NUMBER = 1 MODULE NAME = UTSUB 
VECTOR TABLE OFFSET NAME = SAVNRS OFFSET VALUE= 1152 
SDRORQ -- QUEUE I/O REQUEST (INTERNAL ENTRYPT) 
ROUTINE VERSION NUMBER = 1 MODULE NAME = DRSUB 


VECTOR TABLE OFFSET NAME 


= DROROS OFFSET VALUE= 1160 


RMI, 
a 


CHAPTER 8 


HANDLING SPECIAL USER BUFFERS 


Some drivers need to handle user buffers in addition to the buffer 
that the Executive address-checks and relocates in a normal transfer 
request. Address-checking and relocation operations must take place 
in the context of the task issuing the I/O request, because the 
mapping registers are set for the issuing task. However, in the 
normal driver interface, the task context after the call to SGTPKT is 
not, in general, that of the issuing task. 


Thus, drivers that need to handle special buffers must be able to 


refer to the I/O packet before it is queued, while the context of the 
issuing task is still intact. 


8.1 DRIVER CODE 


The coding shown in this chapter is an excerpt from a driver that 
illustrates the handling of a special user buffer. The key points 
are: 


1. The UC.QUE bit has been set in the control byte (U.CTL) of 
the UCB for each device/unit. 


2. The routine (ZZINI) that is defined as the I/O initiation 
entry point in the driver dispatch table (DDT$) macro call 
performs the following actions: 


1. Retrieves the user virtual address and address-checks it 


2. Relocates the virtual address and stores the result back 
into the packet 


3. Inserts the packet into the I/O queue and continues 
execution inline to the entry point BMINI, which calls 
SGTPKT 


DRIVER CODE 


3. The driver propagates its own execution by branching back to 
BMINI to call S$GTPKT. 


DRIVER CODE 


se 


-TITLE BMTAB - 
~-IDENT /01/ 


DATA BASE FOR BLOCK MOVE DRIVER 


COPYRIGHT (c) 1981, 1982 BY 
DIGITAL EQUIPMENT CORPORATION, MAYNARD 
MASSACHUSETTS. ALL RIGHTS RESERVED. 


~Se@ BH BH BH WS 


;THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED 
7;AND COPIED ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE 
;AND WITH THE INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS 
7;SOFTWARE OR ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR 
;OTHERWISE MADE AVAILABLE TO ANY OTHER PERSON. NO TITLE TO AND 
;OWNERSHIP OF THE SOFTWARE IS HEREBY TRANSFERRED. 

;THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
;NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
; EQUIPMENT CORPORATION. 

;DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
ITS SOFTWARE ON EQUIPMENT THAT IS NOT SUPPLIED BY DIGITAL. 


LOADABLE DATA BASE FOR EXAMPLE BUFFERED I/O DRIVER 


~™~G@ ~BwZeE BS WHE WE VS WH BVH WE 


MACRO LIBRARY CALLS 
-MCALL CLKDFS 
»-MCALL HWDDFS 
»-MCALL SCBDFS 
-MCALL UCBDFS 
CLKDFS *>DEFINE CLOCK BLOCK OFFSETS 
HWDDFS >DEFINE HARDWARE REGISTERS 
SCBDFS’- ,,SYSDEF *>DEFINE SCB OFFSETS 
UCBDFS >DEFINE UCB OFFSETS 
SDAT:: 
: BM DCB 
SDCB::3 
«WORD ) > D.LNK 
»WORD »BMO - D.UCB 


DRIVER CODE 


eASCII /BM/ - D.NAM 
-BYTE 0,1-1 - D.UNIT,D.UNIT+H1 
»WORD BMND-BMST > D.UCBL 
«WORD $0 * D.DSP 
> D.MSK -— FUNCTION MASKS : 
» WORD 33 ° LEGAL 0-17 IO.KIL,IO.WLB,IO.ATT 
. LOSsDET 
» WORD 31 : CONTROL 0-17 IO.KIL,IO.ATT,1IO.DET 
»WORD 0) > NOOP 0-17 
«WORD 0 > ACP 0-17 
.»WORD 4 > LEGAL 20-37 IO.WVB 
» WORD 0 > CONTROL 20-37 
- WORD 0 > NOOP 20-37 
.» WORD 0 > ACP 20-37 
» WORD 0 > D.PCB 
; BM UCB'S 
PRO=0 
~1F DF MSSMUP 
» WORD ) 
-ENDC 
~-BMO:: 
» WORD SBMDCB > U.DCB 
«WORD 2 ° U.RED 
-BYTE UC .QUE,0 * U<CTL;UsSTS 
-BYTE 0,US.OFL - U.UNIT,U.ST2 
«WORD DV.REC - U.CWl 
» WORD 0 > U.CW2 
«WORD 0 > U.CW3 
WORD 712% > U.CW4 
«WORD SBMO > U.SCB 
» WORD 0 2 U,ATT 
.»WORD 0,0 > U.BUF,U.BUF+t2 
.» WORD 0 > U.CNT 
BMND=. 


=e BP BE BW 


BM. SCB.S 


SBMO: 


SEND: 


i 


DRIVER CODE 


» WORD Vee! ; S.LHD 

e WORD 0,0,0,0 ; S.FRK 

e WORD 0 ; §.KS5 

e WORD 0 ; SPKT 

BYTE 0,0 ; S.~CTM,S.1ITM 

BYTE 07.0 :: SsSTS,S.ST3 

«WORD 0 > Seo l2 

e WORD 0 ; SeKRB - NO KRB SINCE NO CONTROLLER 
e END 


eTITLE BMDRV - BLOCK MOVE DRIVER 
~IDENT /01/ 


;COPYRIGHT (c) 1981,1982 BY DIGITAL EQUIPMENT CORPORATION. 
7;ALL RIGHTS RESERVED. 


;THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED 
;OR COPIED ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE. 


me 2 BO WH BMS WE WH VWSH BVO BQ ZS BVH VS WO VE WE WH WH WH WH WH WH BMWS WH “WOE 26 =P BR WS VW 


THIS IS A SAMPLE DRIVER WHICH DEMONSTRATES HOW TO USE SOME 
OF THE MORE SOPHISTICATED EXECUTIVE SERVICES AVAILABLE TO 
I/O DRIVERS. THIS DRIVER DEMONSTRATES: 


1) THE CHECKING OF ADDITIONAL USER BUFFERS PRIOR TO QUEUEING 
AN I/O PACKET. 


2) USE OF THE CLOCK QUEUE FROM A DRIVER. 

3) USE OF THE BUFFERED I/O MECHANISM 

4) USE OF THE GENERAL BUFFERED I/O KERNEL AST MECHANISM 
5) USE OF REGION LOAD KERNEL ASTS 


6) USE OF BLXIO 


THIS DRIVER UNDERSTANDS PRECISELY ONE QIO, WHICH IS: 
eee IO.WLB,.....,<DEST-~BUFFER, LENGTH , TIME,SRC-BUFFER> 
OR 
ITO.WVB 


THE DRIVER QUEUES A CLOCK BLOCK FOR TIME TICKS AND AT THE 


o=> 


DRIVER CODE 


END OF THAT TIME INTERVAL COPIES THE SOURCE BUFFER TO THE 
DESTINATION BUFFER. IF POSSIBLE, THE REQUEST IS BUFFERED 
INTERNALLY WHILE THE CLOCK REQUEST IS POSTED. 


=e 26 @2e =e 


eMCALL CLKDFS, PKTDFS 


CLKDFS ;DEFINE CLOCK BLOCK OFFSETS 
PKTDFS ;DEFINE I/O PACKET OFFSETS 


DEFINE MAXIMUM TRANSFER LENGTH WHICH WILL BE BUFFERED 


=6 BSE WS 


BUFLIM = 100. 


DDTS BM, ,NONE,,,NEW 


* -—- BMINI - I/O INITIATION ENTRY POINT 


INPUTS: 


DROIO (BECAUSE THE UC.QUE BIT IS SET IN THE UCB) SETS THE 
REGISTERS TO THE FOLLOWING: 


Rl = ADDRESS OF I/O PACKET 

R4 = ADDRESS OF SCB 

R5 = ADDRESS OF UCB 
OUTPUTS : 


IF THE SPECIFIED CONTROLLER IS NOT BUSY AND AN I/O REQUEST IS 
WAITING TO BE PROCESSED, THEN THE REQUEST IS DEQUEUED AND THE 
I/O OPERATION IS INITIATED. 


I/O REQUEST PACKET FORMAT: 


=e "8 =6 %O6@ =6@ ~W“S Re B~SH WH ZS wWHE WH VE WHE WH WHE WE WE BG BW WS VW WE WH BH WE BH WE 


I.LNK -- I/O QUEUE THREAD WORD. 

I.PRI/I.EFN -- REQUEST PRIORITY, EVENT FLAG NUMBER. 

I.TCB -- ADDRESS OF THE TCB OF THE REQUESTER TASK. 

I.LN2 -- POINTER TO SECOND LUN WORD IN REQUESTER TASK 
HEADER. 

I.UCB -- UCB ADDRESS OF DEVICE 

I. FCN -- I/O FUNCTION CODE (IO.WLB). 
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aoe 
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fi 


=e ~e @=F BE WEN WS BS BE WO VE BS WE BHF WH BW WE 


~ —™@e@ BO BE BQ WE 


BMINI: 


@=e@ BE BWE 


=e BE WE BWE 


=e@ ®e@ 2@ B=@ BE WE BWE BE 


DRIVER CODE 


I.IOSB -- VIRTUAL ADDRESS OF I/O STATUS BLOCK. 

L«TOSBF2 -- RELOCATION BIAS OF I/O STATUS BLOCK. 

I.IOSBt+4 -- I/O STATUS BLOCK ADDRESS (DISPLACEMENT + 
140000). 

I. IOSB+6 -- VIRTUAL ADDRESS OF AST SERVICE ROUTINE. 

I.PRM -- RELOCATION BIAS OF SOURCE BUFFER. 

I.PRM+2 -- BUFFER ADDRESS OF I/O TRANSFER. 

I.PRM+4 -- NUMBER OF BYTES TO BE TRANSFERED. 

I.PRM+6 -- TIME DISPLACEMENT IN TICKS 

I.PRM+10 -- VIRTUAL ADDRES (TO BECOME RELOCATION BIAS) OF 
DESTINATION BUFFER 

I.PRM+12 -- FILLED IN WITH DISPLACEMENT ADDRESS OF 
DESTINATION BUFFER 

I.PRM+14 -- USED TO STORE BUFFER/CLOCK BLOCK ADDRESS 

I.PRM+16 -- FILLED IN WITH PCB ADDRESS OF OUTPUT BUFFER 


e-ENABL LSB 


kKkA KK KKKRKKKRKRR KKK KK KKK KK KKK KKK KK KKK KKK KKRKRKRKRKKRKRKRKKRKRKRKEKEK 


* * 
= INITIATION ENTRY POINT . 
* . * 


KKAERKRKKKKRKKKKRKRKRKRKRKRKEKRKRKRRKKRKRKKRKRKRKR KK KRKRKRKKRRKKKKRKRKRKKRKRKRKA RK KKK 


° PRE-QUEUING INITIALIZE ENTRY POINT 
kkk kekkekkkekkekhkekekekekekeReeeRKRKRKRKKRKR KR RRR RRR KEE 
de +d 
* ADDRESS CHECK THE SOURCE BUFFER WHILE THE TASKS > 
~ CONTEXT IS LOADED, AND FILL IN THE NECESSARY . 
x PARAMETERS IN THE I/O PACKET * 
¥ ¥e 
kkeaKKKKKR KKK KKK KKK KKK KERR KKK KKRRKRRERKEES 

MOV R1,R3 * COPY ADDRESS OF I/O PACKET 
MOV I.PRM+10(R1),RO ; GET VIRTUAL ADDRESS OF SOURCE 
| ¢ BUFFER 
MOV I.PRM+4(R3),R1 ; AND LENGTH OF SOURCE BUFFER 
fe ce ee ee a ee ee me ee ee ee ee ee ee ee rrr rere 


THE INPUT PARAMETERS FOR SCKBFR ARE: 


RO = STARTING ADDRESS OF BLOCK TO BE CHECKED 

Rl = LENGTH OF THE BLOCK TO BE CHECKED 

SATTPT = ADDRESS OF I.AADA IN I/O PACKET 
(ESTABLISHED IN DROQIO) 
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CALL 


BCC 


DRIVER CODE 


CURRENT TASK HEADER MUST BE MAPPED THROUGH APR 6 
(ESTABLISHED BY DIRECTIVE DISPATCHER) 


THE OUTPUT PARAMETERS ARE: 


‘o) 
it 


O IF CHECK AND PACKET UPDATE SUCCESSFUL 


I.AADA OR I.AADA IN PACKET POINTS TO 
RELATED ADB, P.IOC, A.IOC INCREMENTED 


@) 
I 


1 IF CHECK UNSUCCESFUL OR I.AADA, I.AADA 


ALREADY FILLED IN 


SCKBFR 


10$ 


™=@ we WD 


CHECK BUFFER, INCREMENT A.IOC AND 
P.IOC FOR APPROPRIATE REGIONS 
IF CC ALL WAS OK 


RHEEAEKEKKEKKRKEKKEKKEKKKKRKKRKRKKRKRKRRKKRKRKRKRKRKRKKRRK KKK KRKRKKRKRKRKRKRKRKRKRKRKRKKRRERSE 


* 
* 
* 


SOURCE BUFFER WAS ILLEGAL, FINISH I/O HERE 


* 
* 
* 


RKEAEKKKRKEKEKEKKEKEKEEKRKEKEREEKREKKRKEKRKEKKEKKRKKRRKRKRKKRKRKRKKKRKRKRKRKRKRKRKRKRKRKRKRKRKRKRKEKK 


MOV 
CLR 


IE.SPC&377,R0 
R1 


e 
a 
e 
a 


SET COMPLETION STATUS 
AND NUMBER OF BYTES TRANSFERRED 


=e *ZE WH BZ VS BWH WH WH WH WE VE WH WH ZH WES 
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DRIVER CODE 


THE INPUT PARAMETERS FOR SIOFIN ARE: 


RO = FIRST WORD OF I/O STATUS TO RETURN 
Rl = SECOND WORD OF I/O STATUS TO RETURN 
R3 = ADDRESS OF I/O PACKET 


THE OUTPUT PARAMETERS ARE: 


R4 IS DESTROYED 


CALLR SIOFIN > COMPLETE I/O AND EXIT DRIVER 


KREKRKEKEKKKEKEREKEKREKEKEREKEKEKEKKEKRREKRKERKKEEREKRKKKRKKKKRKKRKRKRKRKRKRRKRKKRKK 


Fe te 
* BUFFER WAS LEGAL, CONVERT VIRTUAL ADDRESS TO * 
~ ADDRESS DOUBLEWORD AND STORE PARAMETERS m 
* te 
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THE INPUT PARAMETERS FOR SRELOC ARE: 
RO = USER VIRTUAL ADDRESS TO RELOCATE 


THE OUTPUT PARAMETERS ARE: 


Rl = APR6 RELOCATION BIAS OF USER BUFFER 
R2 = DISPLACEMENT IN BLOCK + 140000 
4—-—-—-~--—--——— — - — — rrr rrr + 
CALL $RELOC ; RELOCATE BUFFER ADDRESS 
MOV R1,I.PRM+10(R3) ; SAVE APR BIAS OF SOURCE BUFFER 
MOV R2,1.PRM+12(R3) ; AND DISPLACEMENT ADDRESS 
CLR I.PRM+16(R3) ; INDICATE NOT BUFFERED I/O 
KE IKKKEKKRKKRKEKKERKKKRKRERKREKRRKKERERKREREKREKRKRKREKRERREKEKEKREKEKEKERKKEKKREKE 
* * 
e NOW QUEUE THE PACKET IN THE DEVICE QUEUE 
& 


KKK KKK IKK KH HK KKK KKK HII HK KKK KKK KKK KEEKREKEEKERKRKEKEKKRKKKKRKRKKKE 
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DRIVER CODE 


MOV R4,RO * COPY POINTER TO I/O QUEUE LISTHEAD 
MOV R3,Rl * AND ADDRESS OF I/O PACKET 
mee ee + 
THE INPUT PARAMETERS FOR SOQINSP ARE: 
RO = ADDRESS OF THE TWO WORD LISTHEAD 
Rl = ADDRESS OF THE PACKET TO BE INSERTED 
NO OUTPUT PARAMETERS 
fee cee ee a em mm em Se em ae enh ee ine he men mine ms ne cam em mh ee i ec ene ee ee eet ah ae en ee ee re a en ee ee ee ee es as + 


CALL SOINSP ° INSERT PACKET IN QUEUE 


~@ BG WE WH WE 


®e *e we WS WE BSH BO VWE WHE BE WHE BW] VE WSO WH BW VS 


BMINI: 


© 
Ps 
ee 
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DRIVER CODE 


RRHEKKKKKRKRKKKKRKRKRKRKRKRRKRKRKRKKKRKRKRKRKKKRKRKRKKKRKR KR KRKRKRKKRKR KKK 
& * 


* BEGIN SERIAL PROCESSING OF I/O PACKETS * 
* * 


RREEEKKEKKEKKEKKKKKRKRKRKKKKRKRKRKRKRRKRKKRKRKRKKKRKRKRKRKRKRKKRKRKRKRKRKRKKRKKRKKRKKKKKRRKRKEK 


THE INPUT PARAMETERS FOR SGTPKT ARE: 
R5 = ADDRESS OF THE UCB OF REQUESTING UNIT 


THE OUTPUT PARAMETERS ARE: 


C = 0 IF A REQUEST WAS SUCCESSFULLY DEQUEUED 
Rl = ADDRESS OF THE I/O PACKET 
R2 = PHYSICAL UNIT NUMBER 
R3 = CONTROLLER INDEX 
R4 = SCB ADDRESS OF CONTROLLER 
R5 = UCB ADDRESS OF UNIT 

C = 1 IF UNIT BUSY OR NO PACKETS QUEUED 

fa ee ee ee ee ee ee ee 4 
CALL SGTPKT ATTEMPT TO GET A REQUEST 
BCC 20S IF CC WE GOT ONE 


RETURN DEVICE BUSY OR QUEUE EMPTY 


REFERENCE LABEL 
KHKKKKKEKKRKKKKKRKEEKEKEKE EKER KEKE KKKKKKKRKKEKKKKKKKKKKKEKRKAKE 
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Fe ye 
- ATTEMPT TO ALLOCATE CLOCK BLOCK - 
# Fe 


KEKEKKEKRKKEKKEKRKEKREKRKREKKEKEKEEKKRKEKKRKKKARKEKKEKKRKRKRKRKRKRKKRKRKRKRKRKKRKRRRKRKRKRKEEE 


MOV R1,R3 > COPY I/O PACKET ADDRESS 
MOV C.LGTH,R1 ; SET LENGTH OF CLOCK BLOCK 


THE INPUT PARAMETERS FOR SALOCB ARE: 
Rl = SIZE OF THE BLOCK TO ALLOCATE (IN BYTES) 


THE OUTPUT PARAMETERS ARE: 


C = 0 IF A BLOCK WAS SUCCESSFULLY ALLOCATED 
RO = ADDRESS OF THE ALLOCATED BLOCK 
Rl = LENGTH OF THE ALLOCATED BLOCK 
C = 1 IF NO BLOCK ISCURRENTLY AVAILABLE 
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DRIVER CODE 


CALL SALOCB ° ATTEMPT TO ALLOCATE 
BCC 30$ ° IF CC SUCCESSFUL 
MOV IE.NOD&377,RO ; SET I/O STATUS 


=e 26 ~@ BF B@ ~WH WS BG WH WHE BS WH BWA BSH WS 
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DRIVER CODE 


THE INPUT PARAMETERS FOR SIOALT ARE: 


RO = FIRST WORD OF I/O STATUS BLOCK 


Rl = SECOND WORD OF I/O STATUS BLOCK 

R2 = STARTING AND FINAL RETRY COUNTS 
(IF AN ERROR LOGGING DEVICE) 

R5 = UCB ADDRESS OF UNIT TO COMPLETE 


THE OUTPUT PARAMETERS ARE: 


R4 IS DESTROYED 


CALL SIOALT AND COMPLETE THE I/O 


BR BMINI ; GO LOOK FOR MORE WORK 

MOV RO,I.PRM+14(R3) ; SAVE ADDRESS OF CLOCK BLOCK 
KREEEKAKKKRKKKKKRKRKRKRKRKRRKRKRKRKRKRKRKRKRRKKRKRKRKR RRR RRR KKRKRKRKRRKRKRRKRKRKRKRKRKRKRKKREK 
* * 
. DETERMINE IF I/O REQUEST IS BUFFERABLE 
* * 


KHREKKKEEKKKEKREKRKEKEKKREEKRKEKREKKKREKKRKEKKKKRKRKRKRKRKRKRKRKRKRKRKRKKKRKRKRKRRKRKRRKRKRKRKREKAKRK 


THE INPUT PARAMETERS FOR STSTBF ARE: 
R3 = ADDRESS OF I/O PACKET TO TEST 


THE OUTPUT PARAMETERS ARE: 


C = 0 IF REQUEST MAY BE BUFFERED 
C = 1 IF REQUEST MAY NOT BE BUFFERED 
$—-—----—-—--------~--~+----- --- -- - - - - - - - - - - - - - - - - - - - - - - - - - - - = - + 
CALL STSTBF > TEST FOR BUFFERABLE I/O REQUEST 
BCS 40S > IF CS CAN'T ALLOCATE A BUFFER 


KEEKEKKKKKKRKKEKHEKK KKK KE KKEKREEKKKEKEKEKKEKRREKREKRERKEREKEKEKKEKERERKEKKEKKEKE 


* ¥e 
x ATTEMPT TO ALLOCATE A BUFFER : 
¥ 


KIKI KKK KKK KEKE KKRKKEKEKEKRKKKKERRKKRKKRKEKRKKRKKKKEKKER 


=e @=6@ BSH BO 


MOV 
CMP 
BHI 


DRIVER CODE 


IT.PRM+4(R3),R1 
Rl, BUFLIM 
40S 


~™e@ we ABS 


GET LENGTH OF BUFFER 
BIGGER THAN BUFFER LIMIT ? 
IF HI YES, DON'T BUFFER 


@e@ @=@ B@ B=@ BE BVO WE WE BWE WE WE WF BWE WH WES 
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DRIVER CODE 


THE INPUT PARAMETERS FOR SALOCB ARE: 

Rl = SIZE OF THE BLOCK TO ALLOCATE (IN BYTES) 
THE OUTPUT PARAMETERS ARE: 

C = 0 IF A BLOCK WAS SUCCESSFULLY ALLOCATED 


RO = ADDRESS OF THE ALLOCATED BLOCK 
Rl = LENGTH OF THE ALLOCATED BLOCK 


C = 1 IF NO BLOCK ISCURRENTLY AVAILABLE 
+———-—-—-—--—— —-— ~~ —- - — - - - -|- 
CALL SALOCB ° TRY TO ALLOCATE BUFFER 
BCS 40s ° IF CS COULDN'T GET ONE 


KHEKKEKKEKEKEKRKEKKKEREKEKRKRREKKKEKKREKRKKEKKKKKKKKKKRKKRKRKKKKRKRKRKKRKKRKRKRKRKRKRKKSE 


k * 
* COPY USER BUFFER TO INTERNAL BUFFER " 
* * 


REEKKEKEKERKEKKEREKKEKREREKRKRERREERERKERKEKRRERKEKRRKRKREKRKKKKEKRKEKRKKRKRKEEKKEEE 


MOV RO,R4 ° SET ADDRESS OF DESTINATION BUFFER 
MOV R3,R5 * SAVE ADDRESS OF I/O PACKET 
MOV I.PRM+4(R5),RO 3; SET LENGTH OF TRANSFER 
MOV I.PRM+10(R5),R1 ; SET BIAS OF SOURCE BUFFER 
MOV I.PRM+12(R5),R2 ; AND DISPLACEMENT 
BIC 140000,R2 - STRIP OFF APR6 ADDRESS BITS 
BIS 120000,R2 ° AND SUBSTITUTE APR5 
MOV R4,1.PRM+10(R5) ; SET INTERNAL BUFFER ADDRESS INTO 
© PACKET 
fom ee rrr +- 


THE INPUT PARAMETERS FOR SBLXIO ARE: 


RO = NUMBER OF BYTES TO MOVE 
Rl = SOURCE APR 5 BIAS 

R2 = SOURCE DISPLACEMENT 

R3 = DESTINATION APRO6 BIAS 

R4 = DESTINATION DISPLACEMENT 


THE OUTPUT PARAMETERS ARE 


RO ALTERED 
R1,R3 PRESERVED 


@=~@ 26 236 WO 
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DRIVER CODE 


R2,R4 POINT TO LAST BYTE OF SOURCE/DESTINATION +1 


CALL SBLXIO >; COPY TO INTERNAL BUFFER 


KRHKRKKEKEKHEKEERREKKKEREKEREKEEREREEKERREKKERERKRERKEKRKKEKRRKRKRKEKRKRKRKRKKRRKRKRRKKRE 


* ke 
. CONVERT TO BUFFERED I/O REQUEST ig 
de x 


KHIKKKIEKKKKEKEKKEKEKEHERKEKRERKKKKRKKRKKKKKK KKK KKK KKK RKKKRKRKKKRRKKKRER 


MOV R5,R3 > COPY I/O PACKET ADDRESS BACK 
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DRIVER CODE 


THE INPUT PARAMETERS FOR SINIBF ARE: 
R3 = ADDRESS OF THE I/O PACKET TO BUFFER 


NO OUTPUT PARAMETERS. 


CALL SINIBF * INITIALIZE BUFFERED I/O 


KRREKKEKRERKEEKKEEEKRERKEKEKERKERKEKKKRKRKRKKKKRKRKRKRKR KKK KKRKKKRKKRKKK KKK KRKRRKRKK 


¥ #e 
* QUEUE THE CLOCK BLOCK . 
* #e 


RHAEEREKRKEKEKKEKREKEEKEKRKERERERREKEKEKERERERERKERERERKREKEKRKEKRREKEEKEKKRRKRKERSE 


MOV I.PRM+14(R3),RO ;: GET ADDRESS OF CLOCK BLOCK 

MOV CLKSRV,C.SUB(RO) ; SET ADDRESS OF SUBROUTINE 

CLR Rl ° HIGH ORDER DELTA TIME 

MOV I.PRM+6(R3) ,R2 °* LOW ORDER PART 

MOV C.SYST,R4 > SET REQUEST TYPE 

MOV R3,R5 ° USE PACKET ADDRESS AS IDENTIFIER 

po --- + + + ee == + 


THE INPUT PARAMETERS FOR $SCLINS ARE: 


RO = ADDRESS OF THE CLOCK BLOCK TO QUEUE 
Rl = HIGH ORDER HALF OF DELTA TIME 


R2 = LOW ORDER HALF OF DELTA TIME 
R4 = REQUEST TYPE 
R5 = ADDRESS OF REQUESTING TASK OR IDENTIFIER 


NO OUTPUT PARAMETERS. 


CALLR SCLINS > QUEUE CLOCK BLOCK AND TEMPORARILY 
. EXIT THE DRIVER 


ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee 
* * 


~ C1508. K ENTRY POINT x 


B17 


=e BG BWP 


=@ =e B=SE BO BS WS 


CLKSRV: MOV C.TCB(R4),R5 


~e 6 ™=O6 =O =@G =B™Q WS 


DRIVER CODE 


* * 
RREKEKKEKEKRKEKRKRREKKEKRREKEKRREEKREKRERREKERKEREKEREKRKEKREKREKKEKRKRKRKRKRKRRRKRKKRKRKKRKRKRKREKEE 


KRREEKKEKEKEKEKEKKEKREKRKEKEKEKEKKEKEKRKRREKREKEKEKEKEKRKKREKKRKEKRK KKK KRKRKKRKRKRKKRKERKESE 


* * 
= CHECK TO SEE IF THE I/O WAS BUFFERED * 
* * 


REKEKKEKEKRKEKEKEKKEKRRERKERKREKKRKEEKRKEKRKEKEKRREKREKREKRKEKKEKEKKKRRKRKRKRRRKRKKKRKRKKRKEESE 


; GET ADDRESS OF I/O PACKET 
TST I.PRM+16(R5) ; WAS IT BUFFERED I/O 
BNE 50$ ; IF NE YES, GO QUEUE KERNEL AST 


KREKEKEEKEEKKEKEKEKEKEEKEKEKREKRKREERKREKRKEKRKEEKKERREKREKRRKREKRKRERKRREKRKRKRRRKRKRKRREKRERK 


* * 
- COULDN'T BUFFER, PERFORM COPY HERE AND NOW . 
* *k 


RREKEKEKKEKEKEKREKEKKREKREKEKEREKEKRHEKEKRKEKREKRKEREKRREREKRRKKRRKRKRKRREKRRERKKRKEKRKRRKREKKE 


MOV IT.PRM+4(R5),RO ; SET LENGTH TO TRANSFER 

MOV I.PRM+10(R5),R1 3; BIAS OF SOURCE BUFFER 

MOV I.PRM+12(R5),R2 ; DISPLEACEMENT OF SOURCE 

BIC 140000,R2 ; STRIP OFF APR6 ADDRESS BITS 
BIS 120000,R2 ; AND CONVERT TO APR5 

MOV IT.PRM(R5),R3 ; SET BIAS OF DESTINATION 
MOV I.PRM+2(R5),R4 3; SET DISPLACEMENT 


~™2e we =@=@ BG WHE WS = @ 


=@ BE WE WH VE WH WE WS WS WE WS 


DRIVER CODE 


ED CED CEEED CRE ED ED ES EE Ge em GE com er GD GED GAR OED GD CHD CED CED WEED ene GTR TOD emi neem cE ea ED CEE EMME OM oD CED CRE GED ED GD Ge ee GED EE cm ee GEE GEE eee GED eu ese OUD aa eam am eae comp cum coum 


THE INPUT PARAMETERS FOR SBLXIO ARE: 


RO = NUMBER OF BYTES TO MOVE 
Rl = SOURCE APR 5 BIAS 

= SOURCE DISPLACEMENT 

= DESTINATION APR6 BIAS 
R4 = DESTINATION DISPLACEMENT 


THE OUTPUT PARAMETERS ARE 


RO ALTERED 
R1,R3 PRESERVED 
R2,R4 POINT TO LAST BYTE OF SOURCE/DESTINATION +1 


CALL SBLXIO ; COPY BUFFER 
MOV I.PRM+14(R5),RO ; GET ADDRESS OF CLOCK BLOCK 
MOV C«LGTH,R1i ; GET LENGTH OF CLOCK BLOCK 


=6 =O BWSE BE WHE WH WE VS BVH WH WS 


BMSUC: 


BMDON : 


DRIVER CODE 


THE INPUT PARAMETERS FOR SDEACB ARE: 


RO = ADDRESS OF BLOCK TO DEALLOCATE 


Rl 


LENGTH OF BLOCK TO DEALLOCATE 


NO OUTPUT PARAMETERS. 


SDEACB 
R5,R3 

IS .SUC&377,RO0 
T.PRM+4(R3),R1 
I.UCB(R3),R5 


@=G %=B=B@& BG BWH WY 


DEALLOCATE IT 
COPY PACKET ADDRESS FOR SIODON 

SET FINAL I/O STATUS 

AND LENGTH OF TRANSFER = REQUESTED 
GET UCB ADDRESS OF DEVICE 


DRIVER CODE 


THE INPUT PARAMETERS FOR SIODON ARE: 


RO = FIRST WORD OF I/O STATUS BLOCK 

Rl = SECOND WORD OF I/O STATUS BLOCK 

R2 = STARTING AND FINAL RETRY COUNTS 
(IF AN ERROR LOGGING DEVICE) 

R5 = UCB ADDRESS OF UNIT TO COMPLETE 


THE OUTPUT PARAMETERS ARE: 


R4 IS DESTROYED 


=™e@ =@ ~™e @WSE BS BH BH BVH WHE WH WH BWHE BVH WHE WH WS 


Chi S IODON 
BR BMIN1 


COMPLETE THE I/O 


GO LOOK FOR MORE WORK 
KHKKKKKKKKK EKER KEKE KERR KERR EREKEKRAEE RK ARK KEKEKRKREKEKEKKEKKKRKAKKKEKE 


=G ®We 


KRREKEKKEKEKEKEKKEREKEKKEREKRKRKRKEKKRKRKEKKRRKRKEKEKRKRKEKKRKKKRKRKRKRKRKRRKRKKKRKRKR KKK E 


; 
® Fe fe 
g 
: x BUFFERED I/O, CONVERT I/O PACKET TO KERNEL * 
; * AST AND EXIT FROM DRIVER * 
® * afe 
; 


508; MOV R4,R3 * COPY CLOCK BLOCK ADDRESS FOR SREQUE 
MOV I.TCB(R5),RO - POINT TO TCB OF TASK 
TST (R4)+ > SKIP LINK WORD 
MOV AK.GBI,(R4)+ > SET A.CBL=AK.GBI 
MOV KISAR5 ,(R4)+ > SET APR BIAS OF SERVICE ROUTINE 
MOV KATSRV, (R4)+ > SET ADDRESS OF PROCESSING ROUTINE 
MOV R5,(R4)+ > SAVE I/O PACKET ADDRESS IN CLOCK BLOCK 


=e =E6@ BME BW WHE WHE WO WS WH WS 


~Se @WO ™~™~e BSE WE 


=@ @6 BH WO WO 


DRIVER CODE 


THE INPUT PARAMETERS FOR SREQUE ARE: 


RO 
R3 


TCB ADDRESS TO QUEUE AST BLOCK TO 
ADDRESS OF THE PACKET TO QUEUE 


NO OUTPUT PARAMETERS. 


pm ee ee ee + + +++ + 
CALLR SREQUE > QUEUE AST TO TASK 
KRKEAEKEKKKEKEKKERKEKKERREKKEKRKEKEKRARKKRKRKRRKKRRKRKKRRKKRRKRKRKRKR KKK RRR K 
* * 
* K ERNE L A S T EN. <u. YY POINT ™ 
* * 


KRHRKEKEKEKREKKEKERKEKEKRREKERKEEKEERKKEREEKRREKREKRKEKEKKEREKRKEKREKKKRRKEKKRRKRKRKRKKRREKK 


KEKEKKEKEKKKKRKREKEKEREKRRRKRKEEKERREKKEKRERKEEKREEKREKRKEKERKEKRRKEKERKRKKRKEESR 


* * 
n GET PCB ADDRESS AND SEE IF PARTITION IS RESIDENT a 
* * 


KKEKEKKRKEKEKEKKEKRKREKREKKEKKREKEKEKEKREKRKEKERREKREKKEREREEKRKEREKRKERKERREKEKEREREE 


KATSRV: MOV TOCR3) ¢R5 ; GET I/O PACKET ADDRESS 
MOV I.PRM+16(R5),R1 ; GET PCB ADDRESS OF BUFFER REGION 
BEQ 70$ ; IF EQ THERE IS NO COPY TO PERFORM 


ee s=@ =6@ BE BE BH BO WE ZWH BSE WH BSE @BWGE BH BWSE WE 


=e ~O@ ~H BH BWH WH WH WHE 


=e @S@ BSE BWE BW WES 
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DRIVER CODE 


ao 
THE INPUT PARAMETERS FOR STSPAR ARE: 
RO = ADDRESS OF THE PACKET (THE KERNEL AST BLOCK) 
Rl = PCB ADDRESS OF THE PCB CONTAINING THE BUFFER 
R5 = TCB ADDRESS OF ASSOCIATED TASK 
THE OUTPUT PARAMETERS ARE 
C = 0 IF REGION IS RESIDENT AND CAN BE ACCESSED 
C = 1 IF REGION IS NOT RESIDENT AND AST HAS 
BEEN QUEUED 
4+—--------—--—--—-—- - —- ~~ - ~ - - - +. 
CALL STSPAR * REGION IN MEMORY ? 
BCC 60S ° IF CC REGION IN MEMORY 


RHEKREKRKKKKRRKRKRKKRRKKKRKRKRRKRKKRKRKKRKKKRKRKRKRKRKRKKRKRKRKRKKKRRKRRKRKRKRKRKRKRKEKRKEKRKEKK 


* * 
- A REGION AST WAS QUEUED. BUMP BUFFERED I/O COUNT * 
™ BACK UP TO FORCE I/O RUNDOWN IN CASE OF ABORT AND % 
- EXIT AST SERVICE ROUTINE. * 
* * 
* x 


KEKKEKKEKEKEKEKEKEEKEKEREKEEKREKKEEKEKREKEREKEKEKEKKEKEKKKRKKRKKKKKRKRKEKRKKKEKEEK 


MOV I.TCB(R5),RO > GET TCB ADDRESS 

INCB T.TIO(RO) > BUMP BUFFERED I/O COUNT 

RETURN > EXIT AST SERVICE ROUTINE 
keke eK KKK KKK KR KKK KK KKK KR KR KKK KKK RERESE 
* * 
* PERFORM BUFFER COPY OPERATION : 
te 


KKEKKHEKKEKKEKEEKEEKREERKKE KEKE KEKE REKRKEKEKEERERKEKREKEEKREKRKEKEKKEKKKEKKKRKKEKE 


MOV I.TCB(R5),RO ¢ GET TCB ADDRESS OF TASK 

INCB T.10C(RO) ¢ ADJUST REAL I/O COUNT UPWARDS 
MOV I.PRM+4(R5),RO ; GET COUNT OF BYTES 

MOV I.PRM+10(R5),R2 ; SET SOURCE BUFFER ADDRESS 

MOV P.REL(R1) ,R3 - GET STARTING BIAS OF PARTITION 
ADD I.PRM(R5) ,R3 ¢ AND ADD IN OFFSET 

MOV I.PRM+2(R5),R4 ;: SET DISPLACEMENT 


=e “=e ~e “@ BS RE B~SG BSH WH WS WH] BWHE WH BQ BVH WE We WS 


=o @=6 =8 B26 BF @“G BH BE WHE WS 


=e 236 BSE6 B36 B®E 
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DRIVER CODE 


THE INPUT PARAMETERS FOR SBLXIO ARE: 


RO = NUMBER OF BYTES TO MOVE 
Rl SOURCE APR 5 BIAS 

R2 SOURCE DISPLACEMENT 

R3 = DESTINATION APR6 BIAS 

R4 DESTINATION DISPLACEMENT 


THE OUTPUT PARAMETERS ARE 


RO ALTERED 
R1,R3 PRESERVED 
R2,R4 POINT TO LAST BYTE OF SOURCE/DESTINATION +1 


COPY THE BUFFER 
GET BUFFER ADDRESS AGAIN 
GET LENGTH OF BUFFER 


CALL SBLXIO 
MOV I.PRM+10(R5) ,RO 
MOV I.PRM+4(R5),RI1 


=e =@6 WE 


THE INPUT PARAMETERS FOR SDEACB ARE: 


ADDRESS OF BLOCK TO DEALLOCATE 
LENGTH OF BLOCK TO DEALLOCATE 


RO 
Rl 


NO OUTPUT PARAMETERS. 


fo~——--— + + + + ee = + 
CALL SDEACB * DEALLOCATE IT 
KEKKREKEKEKEREKKKEREKKKEKRKEKEKEKREKKEKRRKRKEKRKKKRKRKRKKRKKRKRKRKRKRKRKRKRKR RRR RRR KKESE 
* * 
* IF THIS WASN'T A REGION LOAD AST, FINISH THE I/O x 
* * 


KRREKKEKKEKEKKEKEKERKEKEEKKEKKEKEKEKEEREEKKREEKRKKEEKKKRKKREKRKEKEREKEKKREKRKEREEKKKKRKK 


MOV I.PRM+14(R5),RO ; RETRIEVE AST BLOCK ADDRESS 
Ist (RO) ; WAS THIS A REGION LOAD AST ? 
BNE 80$ ; IF NE YES 

MOV C.LGTH,R1 ; SET LENGTH OF CLOCK BLOCK 


DRIVER CODE 


: f= SS SSS SSS SSS SS SS SSS SS SS SS SS SSS eS SS Se Se SSS SS SSS = 
7 THE INPUT PARAMETERS FOR SDEACB ARE: 
: RO = ADDRESS OF BLOCK TO DEALLOCATE 
7 Rl = LENGTH OF BLOCK TO DEALLOCATE 
: NO OUTPUT PARAMETERS. 
: Sete eee tena ncteatemaencteaaee eee ineealian ten eetenae ete hetaechet ee tenteneteeantentenietenentetenieaheneentententnetennteenieae 
CALL SDEACB ; DEALLOCATE CLOCK BLOCK 
MOV I.IOSB(R5),R3 * GET VIRTUAL ADDRESS OF I/O STATUS 
* BLOCK 
MOV IS.SUC&377,-(SP) ; SET FIRST I/O STATUS WORD 
MTPDS (R3)+ * WRITE FIRST WORD OF STATUS (MAY 
> TRAP) 
MOV I.PRM+4(R5),-(SP) ; SET SECOND WORD OF I/O STATUS 
MTPDS (R3) ° WRITE SECOND WORD (MAY TRAP) 
CLR I. 1OSB(R5) * PREVENT SIODON ATTEMPT TO WRITE 
>; STATUS 
MOV R5,R3 * COPY I/O PACKET ADDRESS 
JMP BMSUC ° FINISH IN COMMON CODE 


* 


* 


=e 86 =G BH WES 


80S: MOV RO,R3 
CLR 10(R0) 
MOV I.TCB(R5),RO 


" RECONVERT REGION LOAD AST TO A TASK AST 


COPY BLOCK ADDRESS 
INDICATE NO BUFFER NEXT TIME 
GET TCB ADDRESS 


KRKEKEKKEKKEKEKKEKKKEKEKEKRREKKRKEKRERKEKEEREKRRERRRKERERKEKRKRKRKRRKEKRKERKRKRKKRKKKKEERSE 


* 
* 
* 


KKEEKKKKEKKEKEKERKEKEKKEKRKEKKKKKKKKKEKRKRKRKRKRKAKRKRKR KKK RRR KKKEKKEKRKEKK 


=e =B3@ BE BWSE BS WS 


™=@ =6 @=6 BE 


DRIVER CODE 


THE INPUT PARAMETERS FOR SREQUE ARE: 


RO 
R3 


TCB ADDRESS TO QUEUE AST BLOCK TO 
ADDRESS OF THE PACKET TO QUEUE 


NO OUTPUT PARAMETERS. 


CALLR SREQUE ; RE-QUEUE TASK AST AND EXIT AST 
; SERVICE 


SEAS SEPT ETE 


=e SBE BH BW WS 


SS we BS BF BG WH WE WE 


DRIVER CODE 


REEKKKKKKKKKKRRKKKKRKRKKEKRKRKRKRKRKKRKRKKKRKKRKRKKKRKKRKRKRKRKRKRKRKKRKRKRKRKRKRKRKRKRKRKRKKEK 


te * 
- MISCELLANEOUS ENTRY POINTS e 
k k 


REEKKKKKKKRKKKKKKRKKKRKRKKKRKRKKKRKRKRKRKKRKRKRKRKKKKKR KKK KKK KKRKRKRKKRKR KKK 


KkKAEKRKKKKKKKKKRKKRKRKKKRKRKRKRKKKKRKRKRKRKKRRKRKRKRKKKRKRKRKRKRKRKRKRKRKRKRKRKKKRKRKRKRKRKKEKRKE 


CANCEL ENTRY POINT 


* * 
te * 
* #* 
- WE COULD DEQUEUE PENDING CLOCK REQUEST, ETC HERE, * 
x BUT WE DON'T, WE JUST LET THEM COMPLETE LATER x 
#e Je 
*& ¥ 


KRREKKKEEKKEKEKEKEKEEKEERRKEKREEKEKRKERERKEREKRREREREKRKEKRKERKKRKRKEKREKER 


DRIVER CODE 


BMCAN : 
° RHEKEEKKEKEKEKEKKEKEKEKEKEKKEKEEKEKEKKKKKKKK KKK KKK KRKRKRKRKRKRKKRKRKKRKRKRKKRKKEK 
° * ¥ 
; . Tao w.E3O-0-r ENTRY (PO. tN 7 i 
° * *k 
0 
; e SINCE THERE'S NO PHYSICAL DEVICE TO TIME OUT, NO-OP * 
° * *k 
HK KKK KARI KK IKK RAKE RAR RAK KREEKRAEARRKRAKAKK KAKA KK KAKA RAK 
BMOUT : 
° KRREEEKKRKERKEKEKKRKKEKRKRKKRKRKRKRKKKRKRKRKRKRKRKRKRKRKRKRKRKRKRKRKRKRKRKKRKKRKRKRKRKKRKKRKRKKRKRKRKRKRK 
° * * 
; a POWE RFAIL ENTRY POINT - 
° x * 
; : POWERFAIL DOESN'T AFFECT NON-EXISTENT DEVICES - 
° * * 
RKERKRKKEKEKKEKRKEKEREKEKEKEKEKKEKEKKKKKKRKRKRKRKKRKRKKRKRRKRKRKRKRKRKKRKR KKK KKK 
BMPWF : 
° KKEKKKKKKKKKKKEKKKKKEKKKKKEKKKKKKKEKEKKKEKEKEKKKKKKAKRKKEKARKKK KKK KEK 
° * * 
; i STATUS CHANGE ENTRY POINTS # 
e * * 
: . DON'T NEED TO TOUCH NON-EXISTENT DEVICE, JUST LET * 
; = EXEC PUT DEVICE ON/OFF LINE = 
° * * 
KRHEEKEKEKKRKKEKEKREKEKKEKRREEKRKEREKRKREKEKEKRREKREKRKERERKERKEREKREKRKRKKKKRRKRKRKRKKRKRKRRKEEE 
BMKRB: 
BMUCB: 

RETURN ; ALL THESE ARE NO-OP FOR NOW 

.END 


CHAPTER 9 


THE PROFESSIONAL VIDEO BITMAP AND FONT STRUCTURE 


This chapter provides reference information to the user in accessing 
the video bitmap and the font structure of the Professional 300 series 
computer. Note that the information provided is for reference, rather 
rather than step-by-step instruction. Familiarity with the hardware 
at the level of the Professional 300 Series Technical Manual (Order 
No. EK-~PC350-TM-001), and with P/OS at the level of Executive 
Directives and the Application (Task) Builder is assumed. 


9.1 THE VIDEO BITMAP 
9.1.1 Application Level Access to the Video Hardware 


Under P/OS, the video generator device registers and display memory 
are generally accessed only by the terminal subsystem, with a higher 
level interface provided for applications. However, it is also 
possible for an application to directly access the hardware. There 
are reasons for both approaches, as outlined below. 


The main reasons for having an application access the hardware 
directly are that the application might be able to: 


@e Achieve faster throughput than if it went through the 
Supported system services. 


@® Provide functionality that the system software doesn't 
Support. 


The main reasons for NOT having an application access the hardware 
directly are as follows: 


@ Future versions of the system software may interact 
differently with the video hardware. An application that 
accesses the hardware directly may not work under all 
versions of P/OS. DIGITAL is not and will not attempt to 
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achieve this type of compatibility. 


® The video hardware may change. The system software keeps up 
with such changes, but if the application accesses the 
hardware directly (thus does not use the system services), it 
will also have to be adapted to account for the video 
hardware changes. 


@® Developing an application that accesses the hardware directly 
requires considerable familiarity with the hardware. The 
relevant sections of the Professional 300 Series Technical 
Manual, along with the contents of this document, are 
pre-requisites to acquiring this familiarity, but are not 
necessarily sufficient by themselves. 


This document will deal only with a Professional running P/OS, but 
some of the information may be useful for applications running under 
other operating systems. 


9.1.2 "Disabling" the Terminal Subsystem 


Before directly accessing the video hardware, an application must 
ensure that the terminal subsystem is not "active". Failure to 
"disable" the terminal subsystem can have unpredictable results, 
including system software failure. 


Steps for "disabling" the video subsystem (P/OS Version 1.7 and 2.0) 
are as follows. 


1. Send a RIS (<ESC>c). This resets the terminal subsystem to 
its initial state, and clears the screen. 


2. Send a “disable cursor" sequence (<ESC>[?251). This turns 
the text mode cursor off. 


After disabling the cursor, the terminal subsystem accesses the video 
hardware only when it is requested to display something - or when it 
blanks the screen at the end of it's time-out period. If the 
application combines requests to the terminal subsystem with it’s own 
manipulation of the video hardware, it must save and restore the 
contents of the following device registers: 


@® Control and Status Register 


@® Plane 1 Control Register 
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@® Plane 2 and 3 Control Register 


@® Memory Base Register (should not be modified at all) 


NOTE 


CAUTION Do not set the interrupt enable bits. The 
results of doing so are unpredictable, and probably 
undesirable. The system could hang or crash. 


9.1.3 Accessing the Video Device Registers 


In the CTI architecture, as on other PDP-1ll buses, devices’ are 
controlled via device registers which appear as memory in the top 8KB 
(the I/O page) of the bus address space. Unlike those on UNIBUS' and 
QO-BUS devices, the device registers on a CTI device do not have fixed 
addresses on the bus. Instead, each option slot has a 128-byte device 
register address space, the location of which can be found in the 
Professional 300 Series Technical Manual. The registers on a given 
module will appear at a fixed displacement within the address space of 
the slot the module is in. This means that in order to access’ the 
device registers on the video, software must determine at run-time 


which slot it is in. The WIMPS Executive Directive provides the means 
for doing this. 


The WIMPS Directive returns a dump of the configuration table, 
including the ID's of the devices in all the slots. Scan the list to 
find out which slot the video is in the video controller has an ID of 
2 in the low byte and 2 in the low 4 bits of the high byte. 


The slot number gives you the bus address. You can then task-build in 
a resident common in partition CTPAGE, which covers the I/O page. 


9.1.4 Access to Video Memory Through the Bus 


It is possible for the CPU to read from and write to the video display 
memory without using the device registers - because the memory can be 
programmed to be on the bus. P/OS uses this configuration. 


The video memory occupies a partition called BITMAP, and the _ system 
video handler creates a region called TFWBMP, which fills it. An 
application can attach the region and map to all or a portion of it. 


THE VIDEO BITMAP 


TFWBMP is 32KB, of which the first 30KB corresponds to the displayed 
portion of the memory. Note that the least significant portion of the 
first word of the region corresponds to the upper left corner of the 
screen. If there is an Extended Bit Option (EBO) in the system, all 
three planes of memory share the same 32KB bus address space. 


To read from or write to any of the planes (whether or not there is an 
EBO), the memory reference enable bit (bit 5) in its plane control 
register must be set to l. If there is an EBO, the memory reference 
enable bit can be set for more than one plane. Reads will come from 
each plane - in ascending order (1, 2, 3) - that has the memory 
reference enable bit set. Plane numbers are defined by the hardware 
and do not necessarily correspond to any software numbering scheme. 
Writes will go to all planes that have the memory reference enable bit 
set. 


Remember that a transfer, once started, can take a long time. Check 
the Done bit before modifying any registers other than the X and Y 
registers unless you are certain that the transfer is complete. 


9.1.5 Natural Images (Reduced Resolution) 


The video hardware normally displays an image with a resolution of 
1024 by 240 pixels, with one bit per pixel per plane. This means that 
a non-EBO system displays black or white pixels only, and an_ EBO 
system can display eight colors or gray levels at a time. 


Using reduced resolution, you can display more grey levels or colors. 
It is possible to have 512 pixels per line with two bits per pixel per 
plane, or 256 pixels per line with four bits per pixel per plane. 


To use reduced resolution in a system with an EBO, the color map must 
be DISABLED by clearing the appropriate bit in the CSR. In this mode, 
the output from plane 1 drives the blue signal, the output from plane 
2 drives the green signal, and the output from plane 3 drives the red 
Signal. At 512 resolution for all planes, this configuration produces 
4 gray levels in a monochrome system, or 64 colors in a color system. 
At 256 resolution, this configuration produces 16 gray levels in a 
monochrome system, or 4096 colors in a color system. 


Resolution is set on a per-plane basis, so different planes can _ be 
displayed at different resolutions. However, this configuration has 
no real usefulness since it can be applied only to a monochrome system 
with an_ EBO. In such a system, the monochrome signal is the sum of 
the three color signals, and several output combinations would 
overload the monochrome monitor. Also, the color map is not used at 
reduced resolution. Therefore, an EBO system cannot be used _ to 
produce any more gray levels than a non-EBO one. 
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The video logic for setting the contents of video memory is unaffected 
by the resolution. The only difference is that as the contents of 
memory are scanned for display, instead of each bit (from the least to 
most significant) of a word being used for a given pixel, each 4 bits 
is used to generate one of 16 possible levels. Thus, the application 
must set 4 bits (in each plane) to define a pixel. 


Note that at ANY resolution, the pixel aspect ratio is not one-to-one. 


9.1.6 The Screen Timer 


A screen time-out feature is built into the terminal subsystem to 
prevent the "burn-in" of a static image in the screen phosphor. The 
terminal subsystem "blanks" the screen if there has been no_ keyboard 
or video activity for thirty minutes. This is accomplished by setting 
the horizontal resolution to "off" in the Plane 1 Control Register. 


For applications that process input from the keyboard, the screen 
timer is not a problem, but for "display only" applications, it can be 
a problem, because the terminal subsystem cannot detect the ongoing 
video activity. One solution to this problem is to send a null byte 
to the screen (via the terminal subsystem) at regular intervals (at 
least every 30 minutes). This will cause the terminal subsystem to 
reset its timer, without causing any visual effects. 


9.1.7 Returning the Video Hardware to the System 


After the application has completed, it must restore the hardware 
device registers, expecially the Plane 1 control register. Failure to 
do so may cause the system to crash when ae_e split-screen scroll or 
insert/delete subsystem should then be re-initialized by issuing a RIS 
sequence. 


9.2 VIDEO FONT STRUCTURE 
This section provides further information for video applications with 


a description of the resident common, and character set and font 
tables. 


9.2.1 VDFNTS Resident Common 


The VDFNTS resident common contains the character set tables and font 
definition tables for the terminal subsystem, and is attached by the 
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subsystem at system boot time. 


At the beginning of the resident common, in a fixed location, is 
information necessary to locating the font and character’ set 
information. This information consists of the following words, in the 
order specified. 


1. A flag indicating the type of pointers in the common. 
Initially the flag is a one (1), indicating that the pointer 
values are self-relative and therefore position independent. 
At system boot time, the pointers are converted to 
position-dependent values for efficiency reasons, and _ the 
flag is set to zero (0). Only the low byte of the word is 
used. 


2. The number of font tables. The value of this word is 
currently three (3), and not used. 


3. Pointers for eight font tables. The pointers point to the 
font data for the zeroth character, rather than the general 
information, in order to facilitate indexing into the table. 
Pointers corresponding to non-existent fonts contain a zero 
(0). The first font is for text while in 80-column mode, the 
second is for text while in 132-column mode, the third is for 
the default graphics-mode font, and the remaining five (5) 
entries are currently unused. 


4. The number of character set tables. 


5. Pointers for sixteen character set tables. The pointers 
point to the translation data for the zeroth character, 
rather than the general information, in order to facilitate 
indexing into the table. Pointers corresponding to 
non-existent character sets contain a zero (0). 


While the above information implies a fair degree of flexibility in 
font design, there are assumptions and restrictions in both software 
and hardware that preclude this. These restrictions, and other 
information about the fonts, are listed below. 


@e The character cells include any Space that occurs’ between 
characters. Therefore, for most characters it is necessary 
to leave a minimum of one row blank, as well as one column of 
pixels in each cell. A spacing of at least two blank columns 
is even more desirable, due to the close spacing of pixels in 
the horizontal direction. In fonts that allow the characters 
to be shifted, a blank column should occur on the _ right. 
There may be some characters (e.g., in the DEC Special 
Graphics set), for which it is desirable to have adjacent 
characters “touch" each other. 


VIDEO FONT STRUCTURE 


@e Character width and height should normally be an odd _ number 
of pixels, in order to produce symmetric characters. 


@ Character cell width must be less than sixteen (16) for fonts 
that allow shifting, and less than seventeen (17) for those 
that do not. 


@ The character cell width for the font used with 80-column 
mode must be twelve (12) pixels, and the character cell width 
for the font used with 132-column mode must be seven (7) 
pixels. 


@® The character cell height must be ten (10). 


@ The pixel aspect ratio for the video display is roughly 2.5 
pixels in the horizontal direction for every one in the 
vertical direction. Therefore a solid horizontal line 
appears brighter than a solid vertical line. If this is to 
be avoided in text-mode characters, the font data must not 
contain two horizontally adjacent pixels which are both "on". 
Also, the fonts must be set up so that the "“edges" of two 
adjacent cells do not both have their pixels "on". This 
restriction does not apply to the graphics-mode font, because 
Graphics text must allow for display in any orientation. 
Fonts that do not satisfy this "adjacency" restriction must 
not set the “shift" attribute. 


@® The "bold" character attribute is only supported with fonts 
which allow the characters to be shifted. "Bold" characters 
are produced algorithmically by shifting the font data 
rightward one pixel and ORing it with the original data. 
This has the effect of "doubling" the vertical lines’ and 
"filling in" the horizontal lines, and therefore producing a 
brighter character in both dimensions. 


9.2.2 Character Set Tables 


The character set tables are used in conjunction with the VT102-mode 
fonts. They provide the information necessary to locate the font data 
for a character, when supplied with the ISO/ANSI character code _ and 
character set information for the character. The zeroth entry 
corresponds to SPACE (2/0), the next ninety-four (94) entries 
correspond to character codes 2/1 to 7/14, and the next ninety-four 
entries correspond to character codes 10/1 to 15/14. 


VIDEO FONT STRUCTURE 


There may be from one to sixteen (16) character set tables for use 
with text-mode, with the first table being aligned on a 64-byte 
boundary. The first four tables determine the default settings for 
character sets GO through G3. Tf there are less than four (4) 
character set tables, the "G" sets which correspond to non-existent 
tables default to the first table. Each character set table begins 
with four bytes of general information about the character set and 
table, in the order listed below. 


1. Size of the entries in the character set translation table, 
in bytes. If the translation table does not specify a font 
entry larger than 255, a value of one (1) may be specified. 
Otherwise, a value of two (2) must be specified. 


2. Character code for the third intermediate character in the 
ISO/ANSI sequence used to designate the charecter set, or 
zero if no such character. 


3. Character code for the second intermediate character in the 
ISO/ANSI sequence used to designate the character set, or 
zero if no such character. 


4. Character code for the final character in the ISO/ANSI 
sequence used to designate the character set. 


This information is followed by the character set translation table. 
The translation table consists of ninety-four (94) entries which 
correspond to each of the possible characters in the character. set, 
and which specify the number of the font entry used to draw the 
corresponding character. Entries which correspond to reserved 
characters should contain a zero, so that the error character is 
displayed. Entry size is one or two bytes, as specified above. 


9.2.3 Font Tables 


The fonts contain the information necessary to produce the visual 
symbols for all supported characters. There are two fonts for VT102 
mode, one for 80-column mode and one for 132-column mode,_ each 
containing all the characters that can be drawn while in VT102 mode, 
and differing only by the size of the characters they produce. 


Fach font is aligned on a 64-byte boundary, and begins with general 
information about the font followed by the data for each of the 
supported characters. The general font. information is listed below, 
with each item occuring in the order shown and occupying one word. 
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1. Maximum character cell wath: in pixels. 

2. Maximum character cell height, in pixels. 

3. Number of bytes of data per character cell row. 
4. Number of bytes of data per character cell. 


9. Number of the character cell row which is modified when a 
character is underlined. The top row is row number one (1). 


6. Font data for the underscore row, which replaces the normal 
data for the row when the character is underlined. 


7. Font attribute flags. Currently, the only supported _ font 
attribute, that character cells in the font may be shifted 
rightward one pixel and ORed with the original to produce a 
"bold" character. 


8. Number of character cell entries contained in the font. 


The general font information is followed by the specified number of 
character cell entries, which are used to draw each of the supported 
characters. Each character cell entry contains the ‘specified number 
of bytes and rows, and consists of the data for each of the rows of 
the character cell. The data for the top row of the character cell 
occurs first within the entry, with the data being displayed low bit 
to high bit from left to right on the display. 


The first five entries of the text-mode fonts are reserved for special 
characters, as specified below: 


® The zeroth entry is the error character, reverse 
question-mark, which is used as the visual presentation of 
SUB and reserved characters. 


@ The next entry is the screen alignment character, a hollow 
rectangle about the size of a capital letter, which is used 
to fill the screen when the DECALN sequence is received. 


@® The next entry is the space character. 


@e The remaining two entries for. special characters are 
currently unused. 


The order and position of other characters in the font is not 
critical, as long as they are the same for the two text-mode fonts. 
The order is usually chosen to facilitate the creation of the 
character set tables. 


VIDEO FONT STRUCTURE 
The currently implemented fonts are as follows: 


80-col 132-col graphic 


cell size (width x height) 12x10 TiO 12x10 
"normal" character w/out descenders (W x H) 9x7 5x7 9x7 

"normal" character with descenders (W x H) 9x9 5x9 9x9 

descender rows 9,10 25°20 9,10 
underline row 9 9 9 
intercharacter row | il 1 1 
intercharacter columns 5 ae Ee Le? 2¢) 142 
font allows shifting yes no no 
data for underline row (hex) 5555 FFFF FFPFF 
size of font row data (bytes) 2 i 2 
size of font data (bytes) 20 10 20 
number of font entries 222 222 189 


Table 9-l: Currently Implemented Fonts 
9.2.4 Cvdata 


This region is created at boot time. It contains a character cell 
view of the screen. The cell view is a linked list of line 
structures. A line structure contains forward and backward links, 
line attributes (double wide, double high top, double high bottom), 
height of the line, number of columns in the line, and the character 
cells of the line. See Figure 9-1. 


+—-------- +—-------- +—-------- +-—------- +—-------- +———---—- +—----\\----- + 
| LICOL | LIHI | LIBL | LIATTR | LIBKWD | LIFWRD | cell data | 
+—-------- +—-------- +—-—-—-—----- +-------- +—--~------ +—------- +—----\\----- + 


+-> Link to next line 
+-> Link to previous line 
+-> Line attributes 
+-> Link to blink list 
+-> Line height 
+-> Number of columns in line 


Figure 9-l: Line Data Structure 

The character cells are one word each. The character attributes’ are 
placed in the high nibble of the high byte to facilitate testing of 
the blink attribute (DABLNK). 


The character set number is placed in the low nibble of the high byte 
to facilitate its extraction. 
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Normally, the character code information for a given cell will have 


a 


value in the range of zero (0) to ninety-three (93), corresponding to 


one of the ninety-four (94) entries within a graphic character 


set. 


However, if the byte value is negative, the character is "special" and 


not contained in a graphic character set. Figure 9-2 describes 
character cell. 


15 12 11 8 7 0 
$——— 4 —-— — $f fe ft 
| CIATTR | CISET | CICODE | 
$a — ff YH fe ff 4 a $f HH 
-+-> DABOLD - Character is bold 

+-> DARVRS - Character is reverse video 
+-> DAUNDR - Character is underscored 
+—-> DABLNK - Character is blinking 


Figure 9-2: Character Cell Structure 


the 


APPENDIX A 


P/OS SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 


This appendix describes the P/OS system macros that supply symbolic 
offsets for data structures listed in Table A-l. 


The data structures are defined by macros in the Executive macro 
library. To reference any of the data structure offsets from your 
code, include the macro name in an .MCALL directive and invoke’ the 
macro. For example: 


-MCALL DCBDFS DCBDFS -Define DCB offsets 


ne 
ar nreeertonin, 
a 


“w 
’ 


NOTE 


All physical offsets and bit definitions are subject 
to change in future releases of the operating system. 
Code that accesses system data structures’ should 
always use the symbolic offsets rather than the 
physical offsets. 


The first two arguments, <:> and <=>, make all definitions global. If 
they are left blank, the definitions will be local. The SYSDEF 
argument causes the variable part of a data structure to be defined. 


All of these macros are in the Executive macro library, 
LB:{1,1]EXEMC.MLB. All except FI11DFS, ITBDFS, MTADFS, OLRDFS, and 
SHDDFS are also in the Executive definition library, 


LB?{ 1,1 EXELIBsOLB. 


Table A-1: 


Macro 


ABODFS 


ACNDFS 


CLKDFS 


CTBDFS 
DCBDFS 
EPKDFS 


F1LIDFS 


HDRDFS 


HWDDFS 


ITBDFS 


KRBDFS 
LCBDFS 


MTADFS 


OLRDFS 


PCBDFS 


Arguments 
<2>,<5=> 


<2:>,<=> 


<2>,<=> 


<3>,<=> 
<3:>,<=>,SYSDEF 
<2:>,<=> 


<3>,<=>,SYSDEF 


<23>,<=> 


<3>,<=>,SYSDEF 


<3>,<=>,SYSDEF 
<3>,<=> 
<3>,<=> 


<3) ,S=> 


<3:>,<=>,SYSDEF 


Summary of System Data Structure Macros 


Data Structures 


Task abort and termination 
notification message codes 


Accounting data structures 
(user account block, task account 
block, system account block) 


Clock queue control block 


Macro Arguments Data Structures 


Controller table 
Device control block 
Error message block 


Files-ll data structures 

(volume control block, mount list 
entry, file control block, file 
window block, locked block list 
node) 

Task header and window block 


Hardware register addresses and 
feature mask definitions 


Interrupt transfer block 
Controller request block 


Logical assignment control block 


ANSI magtape data structures 
(volume set control block) 


On-line reconfiguration interface 


Partition control block and 
attachment descriptor 


PKTDFS 


SCBDFS 
SHDDFS 
TCBDFS 


UCBDFS$ 


<3 ,S=> 


<3>,<=>,SYSDEF 
<3>,<=> 
<3:>,<=>,SYSDEF 


<3:>,<S=>,TTDEF,SYSDEF 


I/O packet, AST control block, 
offspring control block, group 
global event flag control block, 
and CLI parser block 

Status control block 

Shadow recording linkage block 


Task control block 


Unit control block 


ABODFS 


A.l ABODFS 


177774 
177776 
000000 
000002 
000004 
000006 
000010 
000012 
000014 
000016 
000020 
000022 
000024 
000026 
000030 
000032 
000034 
000036 
000040 
000042 
000044 


000046 
000050 
000052 


000000 
000002 
000004 
000006 
000010 
000012 
000014 
000016 
000020 
000022 
000024 


=f 


TASK ABORT CODES 


NOTE: S.COAD-S.CFLT ARE ALSO SST VECTOR OFFSETS 


™e@ @2F WE BH AWS 


S .CTKN=42. 


S.CACT=-4. ; TASK STILL ACTIVE 
S.CEXT=-2. ; TASK EXITED NORMALLY 
S.COAD=0. ; ODD ADDRESS AND TRAPS TO 4 
S.CSGF=2. ; SEGMENT FAULT 
S.CBPT=4. ; BREAK POINT OR TRACE TRAP 
S.CIOT=6. ; IOT INSTRUCTION 
S.CILI=8. ; ILLEGAL OR RESERVED INSTRUCTION 
S.CEMT=10. ; NON RSX EMT INSTRUCTION 
S.CTRP=12. ; TRAP INSTRUCTION 
S.CFLT=14. ; 11/740 FLOATING POINT EXCEPTION 
S.CSST=16. ; SST ABORT-BAD STACK 
S.CAST=18. ; AST ABORT-BAD STACK 
S .CABO=20. ; ABORT VIA DIRECTIVE 
S.CLRF=22. ; TASK LOAD REQUEST FAILURE 
S.CCRF=24. ; TASK CHECKPOINT READ FAILURE 
S.IOMG=26. ; TASK EXIT WITH OUTSTANDING I/O 
S.PRTY=28. ; TASK MEMORY PARITY ERROR 
S.CPMD=30. ; TASK ABORTED WITH PMD REQUEST 
S .CELV=32. ; TI: VIRTUAL TERMINAL WAS ELIMINATED 
S .CINS=34. ; TASK INSTALLED IN 2 DIFFERENT SYSTEMS 
S.CAFF=36. ; TASK ABORTED DUE TO BAD AFFINITY 
; (REQUIRED BUS 
; RUNS ARE OFFLINE OR NOT PRESENT) 
S .CCSM=38. ; BAD CSM PARAMETERS OR BAD STACK 
S .COTL=40. ; TASK HAS RUN OVER ITS TIME LIMIT 
; ABORT VIA DIRECTIVE WITH NO TKTN 


MESSAGE 


TASK TERMINATION NOTIFICATION MESSAGE CODES 


=e BS WE 


T.NDNR=0 > DEVICE NOT READY 
T.NDSE=2 > DEVICE SELECT ERROR 

T .NCWF=4 * CHECKPOINT WRITE FAILURE 
T.NCRE=6 * CARD READER HARDWARE ERROR 
T.NDMO=8. * DISMOUNT COMPLETE 
T.NUER=10. > UNRECOVERABLE ERROR 
T.NLDN=12. * LINK DOWN (NETWORKS) 
T.NLUP=14. > LINK UP (NETWORKS) 
T.NCFI=16. > CHECKPOINT FILE INACTIVE 
T.NUDE=18. > UNRECOVERABLE DEVICE ERROR 
T.NMPE=20. > MEMORY PARITY ERROR 


A-4 


000026 
000030 
000032 
000034 
000036 


000040 


000042 


T.NKLF=22. 
T.NAAF=24. 
T NTAF=26. 
T.NDEB=28. 
T.NRCT=30. 


T.NWBL=32. 


T .NVER=34. 


™=e@ ™=e@ =@ =6 =O BBG BG WE BSE BWE 


ABODFS 


UCODE LOADER NOT INSTALLED 
ACCOUNTING ALLOCATION FAILURE 
ACCOUTING TAB ALLOCATION FAILURE 
TASK HAS NO DEBUGGING AID 
REPLACEMENT CONTROL TASK NOT 
INSTALLED 

WRITE BACK CACHING DATA LOST. UNIT 
WRITE LOCKED 

MOUNT VERIFICATION TASK NOT 
INSTALLED 


A.2 CLKDFS 
o- 
THE FOLLOWING 
000000 C.MRKT=0 
000002 C.SCHD=2 
000004 C.SSHT=4 
000006 C.SYST=6 
000010 C.SYTK=8 
000012 CéCSTP=10. 
-ASECT 
<=0 
000000 C.LNK: .BLKW 
000002 C.ROT: .BLKB 
000003 C.EFN: .BLKB 
000004 C.TCB: .BLKW 
000006 C.TIM: .BLKW 
000012 -=C.TIM+4 
000012 C.AST: .BLKW 
000014 C.SRC: .BLKW 
000016 C.DST: .BLKW 
000020 »BLKW 


CLKDFS$ 


CLOCK QUEUE CONTROL BLOCK OFFSET DEFINITIONS 


CLOCK QUEUE CONTROL BLOCK 


EACH CONTROL BLOCK HAS THE SAME FORMAT IN THE FIRST 


FIVE WORDS AND DIFFERS IN THE REMAINING THREE. 


CONTROL BLOCK TYPES ARE DEFINED: 


=e =6@ @O@ =6 BE BSH WH BW WH ™ @ 


=e 2G BWO a | 


=e =O "=O ™=6 


be pet Re 


7) 


; THERE ARE FIVE TYPES OF CLOCK QUEUE CONTROL BLOCKS. 


MARK TIME REQUEST 

TASK REQUEST WITH PERIODIC 
RESCHEDULING 

SINGLE SHOT TASK REQUEST 

SINGLE SHOT INTERNAL SYSTEM SUBROUTINE 
(IDENT) 

SINGLE SHOT INTERNAL SYSTEM SUBROUTINE 
(TASK) 

CLEAR STOP BIT (CONDITIONALIZED ON 
SHUFFLING) 


CLOCK QUEUE CONTROL BLOCK TYPE INDEPENDENT 
OFFSET DEFINTIONS 


CLOCK QUEUE THREAD WORD 

REQUEST TYPE 

EVENT FLAG NUMBER (MARK TIME ONLY) 

TCB ADDRESS OR SYSTEM SUBROUTINE 
IDENTIFICATION 

ABSOLUTE TIME WHEN REQUEST COMES DUE 


ze ~@™O@ BWE WH WH WS 


CLOCK QUEUE CONTROL BLOCK-MARK TIME 
DEPENDENT OFFSET DEFINITIONS 


START OF DEPENDENT AREA 
AST ADDRESS 


=™Ee ~™SE WH WH DO 


FLAG MASK WORD FOR 'BIS‘' SOURCE 
ADDRESS OF 'BIS' DESTINATION 
UNUSED 


000012 
000012 
000016 
000020 


000012 
000012 
000016 
000020 


™e@ =@ WE BFE WH WHE BAG WH WH WHE ZO 


000012 
000012 
000014 
000016 


000020 
000022 


000000 


-=C.TIM+4 
C.RSI: .~BLKW 
C.UIC: .~BLKW 
C.UAB: .~BLKW 
~=C.TIM+4 

» BLKW 

e BLKW 

e BLKW 


TYPE 6=SINGLE SHOT 


AN IDENTIFIER. 


TYPE 8=SINGLE SHOT 


AN IDENTIFIER. 


-=C.TIM+4 
C.SUB: .BLKW 
C.AR5: e BLKW 
C.URM: e BLKW 
e BLKW 
C.LGTH=. 
«-PSECT 


~e ~e@ =E WE fend feed A ~e ~S WH ~WO 


Ee NO 


fs 


CLKDFS$ 


CLOCK QUEUE CONTROL BLOCK-PERIODIC 
RESCHEDULING DEPENDENT OFFSET 
DEFINITIONS 


2G BG WO w~, @ 


START OF DEPENDENT AREA 

RESCHEDULE INTERVAL IN CLOCK TICKS 
SCHEDULING UIC 

POINTER TO ASSOCIATED UAB 


CLOCK QUEUE CONTROL BLOCK-SINGLE 
SHOT DEPENDENT OFFSET DEFINITIONS 


=e wWE WE WS 


INTERNAL SUBROUTINE WITH 


INTERNAL SUBROUTINE WITH 


wae ae ~@~F WHE WH WH WH VWH WH 


START OF DEPENDENT AREA 
TWO UNUSED WORDS 
SCHEDULING UIC 

C.UAB 


CLOCK QUEUE CONTROL BLOCK-SINGLE SHOT INTERNAL SUBROUTINE OFFSET 
DEFINITIONS 


THERE ARE TWO TYPE CODES FOR THIS TYPE OF REQUEST: 


A 16 BIT VALUE AS 


A TCB ADDRESS AS 


START OF DEPENDENT AREA 
SUBROUTINE ADDRESS 

RELOCATION BASE (FOR LOADABLE 
DRIVERS ) 

URM TO EXECUTE ROUTINE ON 

(MP SYSTEMS, C.SYST ONLY) 
UNUSED 

LENGTH OF CLOCK QUEUE 
BLOCK 


CONTROL 


A.3 


=o ™@6 =O ~S WS WH WHE MWS WH WH WH BWSE WH WH BVH WH] WHE WH WHE WHE WH BWH BQ WH 


000022 
000000 
000000 
000002 
000004 
000006 


000007 
000010 
000012 


000014 
000016 


000020 


000022 
000024 
000026 
000030 
000032 
000034 


D.UNIT 


D.UCBL 


D.DSP: 
D.MSKs: 


D.PCB: 


DCBDF$,,SYSDF 


DEVICE CONTROL BLOCK 


IO.RSD/IO.WSD ARE TT1: 
ONE SINCE THE FUNCTION CODE MASKS ARE DIFFERENT. 
CONCEPTUALLY POSSIBLE TO ADD A USER WRITTEN DRIVER THAT HAS THE 
LOGICAL DEVICE NAME ‘TT' THOUGH IT MUST HAVE DIFFERENT LOGICAL 


UNIT NUMBERS (IE:TT3:) 


e BLKW 
- BLKW 
e BLKW 
e BLKB 


eBLKB 


e BLKW 


e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 


ePSECT 


—— 


Joamed 


Jom 


ae el ee 


26 =@ =6@ ~e@ we BSE BWSJ WH WH BVH WH BS WE WE BVH BVH WHE BW BE 


DCBDFS , ,SYSDF 


THE DEVICE CONTROL BLOCK (DCB) DEFINES GENERIC INFORMATION 
ABOUT THE LOGICAL ACCESS TO THE DEVICE. 
LOWEST AND HIGHEST LOGICAL UNIT NUMBERS (NOT THE PHYSICAL 
UNIT NUMBERS FOUND IN U.UNIT), 
UCB(S), A POINTER TO THE FIRST UCB 
BY D.UNIT ARE ALLOCATED CONTIGUOUSLY TO THE FIRST UCB), 

CLASSIFICATION OF EACH POSSIBLE I/O FUNCTION CODE, AND A 
POINTER TO THE DEVICE DRIVER AND ITS DISPATCH TABLE. 
AT LEAST ONE DCB FOR EVERY LOGICAL DEVICE NAME IN THE SYSTEM. 


THIS INCLUDES THE 


THE LENGTH OF THE ASSOCIATED 


(ADDITIONAL UCBS IMPLIED 
THE 


THE: IS 


FOR EXAMPLE THE LOGICAL DEVICE NAME ‘TT’ IS ASSOCIATED WITH 
THE BITMAP VIDEO (TT1l:) AND THE PRINTER PORT (TT2:). 
MANAGED BY THE FULL DUPLEX TERMINAL DRIVER AND SINCE 
SPECIFIC, TWO DCBS ARE USED RATHER THAN 


BOTH ARE 


IT IS 


LINK TO NEXT DCB 

POINTER TO FIRST UNIT CONTROL BLOCK 
GENERIC DEVICE NAME 
LOWEST UNIT NUMBER COVERED BY THIS 
DCB 

HIGHEST UNIT NUMBER COVERED BY THIS 
DCB 

LENGTH OF EACH UNIT CONTROL BLOCK 
IN BYTES 

POINTER TO DRIVER DISPATCH TABLE 
LEGAL FUNCTION MASK CODES 0-15. 
CONTROL FUNCTION MASK CODES 0-15. 
NOP'ED FUNCTION MASK CODES 0-15. 
ACP FUNCTION MASK CODES 0-15. 

LEGAL FUNCTION MASK CODES 16.-3l. 
CONTROL: FUNCTION MASK CODES 16.-3l. 
NOP’ED FUNCTION MASK CODES 16.-3l. 
ACP FUNCTION MASK CODES 16.-3l. 
LOADABLE DRIVER PCB ADDRESS 


177770 
LITATZ 


177774 


177774 


V77776 
000000 
000002 
000004 
000006 
000010 
000012 


000014 


DRIVER DISPATCH 


& @ Bae WHE 


D.VTOU=-10 


D.VTIN=-6 


we @Q WO WH WO 


D.VCHK=-4 


D.VDEB=-2 
D.VINI=0 
D.VCAN=2 
D.VOUT=4 
D.VPWF=6 
D.VKRB=10 
D.VUCB=12 


me ZS WHE WE WHE WH WS WHE WHE WHE BH WH WE 


DCBDF$,,SYSDF 


TABLE OFFSET DEFINITIONS 


ADDRESS OF ROUTINE IN TTDRV CALLED 
FOR OUTPUT COMPLETION 

ADDRESS OF ROUTINE IN TTDRV CALLED 
FOR INPUT FROM THE CT FIRMWARE TASK 
ADDRESS OF ROUTINE CALLED TO VALIDATE 
AND CONVERT THE LBN. USED BY DRIVERS 
THAT SUPPORT SEEK OPTIMIZATION. 
ADDRESS OF ROUTINE IN TTDRV CALLED TO 
HAVE IT SEND THE NEXT COMMAND IN THE 
TYPEAHEAD BUFFER TO MCR. (NOT USED BY 
P/OS) 

DEALLOCATE BUFFER(S) 

DEVICE INITIATOR 


CANCEL CURRENT I/O FUNCTION 


DEVICE TIMEOUT 

POWERFAIL RECOVERY 

CONTROLLER STATUS CHANGE ENTRY 
UNIT STATUS CHANGE ENTRY 


eIF’ NB SYSDF 


D.VINT=14 >;BEGINNING OF INTERRUPT STUFF 


eENDC 


DDTS 


A.4 DbDTSs 
ta 
- GENERATE THE I/O DEVICE DRIVER DISPATCH TABLE -- DDTS 

eMACRO DDTS DEV ,NCTRLR, INY, INX,UCBSV,NEW,BUF,OPT 

-IF NB <OPT> 

- WORD 'DEV' CHK 

- ENDC 

~-IF NB <BUF> 

WORD 'DEV' DEA 

oIFF 

-IF NB <OPT> 

» WORD 172361 *>ENTRY SHOULD NOT BE USED - CRAS 

-ENDC 

~ENDC 

~-ENABL LSB 

-IF B <INX> 
S'DEV'TBL::.WORD DEV' INI 

~IFF 
S'DEV'TBL::.WORD DEV’ INX 

- ENDC 

«WORD DEV' CAN 

» WORD DEV' OUT 

-IF B <NEW> 

» WORD 655338 

» WORD 0 

» WORD 65531S 

~IFF 

- WORD DEV' PWF 

- WORD DEV'KRB 

» WORD DEV'UCB 

» ENDC 

-IF DIF <INY>,<NONE> 

-ASCII /DEV/ 

-IF B <INY> 

» WORD S'DEV' INT 

~IFF 

-IRP X;<INY> 

» WORD S* DEV’ XxX 

- ENDM 

- ENDC 

«WORD 0 
'DEV'CTB: » WORD 0 

- ENDC 
S'DEV'TBE::.WORD 0 

-IF NB <UCBSV> 
UCBSV: - BLKW NCTRLR 

-ENDC 

-.IF B <NEW> 

BITB #UC.PWF,U.CTL(R5) 


655318: 


A-10 


DDTS 


65531$: BITB #UC.PWF,U.CTL(R5) 
BEQ 65532s 
65533S: BCS 65532S 
JMP DEV' PWF 
65532$: RETURN 
~ENDC 
~-DSABL LSB 
- ENDM 


A-11 


A.5 


000000 
000002 
000000 
000001 
000002 
000010 
000011 
000003 
000001 
000002 
000004 
000010 
000020 


000004 
000020 
000024 
000024 
000026 
000032 
000033 
000034 
000036 
000040 


000041 
000042 
000044 
000045 
000046 
000050 
000052 
000054 
000056 
000057 
000060 
000062 
000001 
000002 
000063 
000064 
000066 
000072 
000076 


~™e BW ~ @ 


o=0 

V-eTRCT: 
V.eITYPE: 
VT .FOR= 
VT.SLI= 
VT .SL2= 
VT .ANS= 
VT UNL= 
V.VCHA: 
VC.SLK= 
VC .HLK= 
VC .DEA= 
VC.PUB= 
VC .DUP= 


V-.LABL: 
V.PKSR: 
V.SLEN: 
V.IFWI: 


, V.FCB: 


V.IBLB: 
V-.IBSZ: 


VeFMAX: 
VWISZ: 


V.~<SBCL: 
VeSBSZ: 
VeSBLB*: 
VeFIEX: 


V.VOWN : 
V.VPRO: 
V.eFPRO: 
V-eFRBK: 
VeLRUC: 


Veolss 

VS.IFW= 
VS -BMW= 
VeFFNU: 
VeEXT: 

V-HBLB: 
V-.HBCS: 
V.LGTH: 


FIIDFS,,SYSDF 


eASECT 


e BLKW 
e BLKB 


- BLKB 


e BLKB 
e BLKW 


e BLKW 
- BLKW 
e BLKB 
e BLKB 
e BLKW 
- BLKW 
e BLKB 


eBLKB 
e BLKW 
eBLKB 
e BLKB 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKB 
- BLKB 
e BLKW 
eBLKB 


- BLKB 
. BLKW 
. BLKW 
» BLKW 


VOLUME CONTROL BLOCK 


ee 


=> Od® 


NO 


Oe 


NOE NO et NO ee ee ee ee eee ee 


“eo Se Ne NSO SO NO Ne Se NS NO Me MO M8 Me Me Me MO NO Me MO MO MO Ne NS Ne MO me MO MO MO ~E TO WO ~OE “SO WS WO BO WO NE WSO we WO we 


F1LIDF$,,SYSDF 


TRANSACTION COUNT 
VOLUME TYPE DESCRIPTOR 

FOREIGN VOLUME STRUCTURE 

FILES-11 STRUCTURE LEVEL 1 

FILES-11 STRUCTURE LEVEL 2 

ANSI LABELED TAPE 

UNLABELED TAPE | 

VOLUME CHARACTERISTICS 

CLEAR VOLUME VALID ON DISMOUNT 
UNLOAD THE VOLUME ON DISMOUNT 
DEALLOCATE THE VOLUME ON DISMOUNT 
SET (CLEAR) US.PUB ON DISMOUNT 
DUPLCATE VOLUME NAME: DON'T DELETE 
LOGICALS 

VOLUME LABEL (ASCII) 

PACK SERIAL NUMBER FOR ERROR LOGGING 
LENGTH OF SHORT VCB 

INDEX FILE WINDOW 

FILE CONTROL BLOCK LIST HEAD 

INDEX BIT MAP 1ST LBN HIGH BYTE 
INDEX BIT MAP SIZE IN BLOCKS 

INDEX BITMAP 1ST LBN LOW BITS 

MAX NO. OF FILES ON VOLUME 

DEFAULT SIZE OF WINDOW IN RTRV PTRS 
VALUE IS < 128. 

STORAGE BIT MAP CLUSTER FACTOR 
STORAGE BIT MAP SIZE IN BLOCKS 
STORAGE BIT MAP 1ST LBN HIGH BYTE 
DEFAULT FILE EXTEND SIZE 

STORAGE BIT MAP 1ST LBN LOW BITS 
VOLUME OWNER'S UIC 

VOLUME PROTECTION 

VOLUME DEFAULT FILE PROTECTION 
NUMBER OF FREE BLOCKS ON VOL HI BYTE 
COUNT OF AVAIL LRU SLOTS IN FCB LIST 
NUMBER OF FREE BLOCKS ON VOL LOW BITS 
VOL STATUS BYTE, CONTAINS FOLLOWING 
INDEX FILE IS WRITE ACCESSED 
STORAGE BITMAP FILE IS WRITE ACCESSED 
FIRST FREE INDEX FILE BITMAP BLOCK 
POINTER TO VCB EXTENSION 

LBN OF HOME BLOCK 

HOME BLOCK CHECKSUMS 

SIZE IN BYTES OF VCB 
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000076 
000000 


000000 
000002 
000001 
000003 
000004 
000006 
000010 


000010 
000000 


000000 
000002 
000004 
000006 
000007 
000010 
000012 
000014 
000015 
000016 


000022 


000026 
000032 
000033 
000012 


000034 
000034 
000035 
100000 


FLIDFS 4S YSDF 


MOUNT LIST ENTRY 


EACH ENTRY ALLOWS ACCESS TO A SPECIFIED USER FOR A 
NON-PUBLIC DEVICE 


TO ALLOW EXPANSION, ONLY THE ONLY TYPE CODE DEFINED 
IS "1" FOR DEVICE ACCESS BLOCKS 


= @ @=~S@ 286 @=G@ BG BVWE BH WH WS 


eASECT 


M.-LNK: .BLKW 1 ; LINK WORD 

M.TYPE: .~.BLKB 1 ; TYPE OF ENTRY 

MT.MLS= 1 ; MOUNTED VOLUME USER ACCESS LIST 
M.ACC: .BLKB 1 ; NUMBER OF ACCESSES 

M.DEV: .~BLKW 1 ; DEVICE UCB 

M.TIs e BLKW 1 ; ACCESSOR TI: UCB 


LENGTH OF ENTRY 


; FILE CONTROL BLOCK 


eASECT 
-=0 
F.LINK: ._BLKW 1 ; FCB CHAIN POINTER 
F.FNUM: .BLKW J ; FILE NUMBER 
F.FSEQ: ._BLKW 1 ; FILE SEQUENCE NUMBER 
e BLKB 1 ; NOT USED 
F.FSON: ._BLKB 1 ; FILE SEGMENT NUMBER 
F.oFOWN: ._BLKW i ; FILE OWNER‘S UIC 
F.FPRO: -BLKW 1 ; FILE PROTECTION CODE 
F.UCHA: .BLKB 1 ; USER CONTROLLED CHARACTERISTICS 
F.SCHA: .BLKB 1 ; SYSTEM CONTROLLED CHARACTERISTICS 
F.HDLB:.BLKW 2 ; FILE HEADER LOGICAL BLOCK NUMBER 
; BEGINNING OF STATISTICS BLOCK 
F.LBN: .~BLKW 2 ; LBN OF VIRTUAL BLOCK 1 IF CONTIGUOUS 
; O IF NON CONTIGUOUS 
F.SIZE:.BLKW 2 ; SIZE OF FILE IN BLOCKS 
F.NACS:.BLKB a3 ; NO. OF ACCESSES 
F.NLCK: .BLKB 1 ; NO. OF LOCKS 
S.STBK=.-F.LBN ; SIZE OF STATISTICS BLOCK 
F.STAT: ; FCB STATUS WORD 
F .NWAC: .BLKB 1 ; NUMBER OF WRITE ACCESSORS 
- BLKB 1 > STATUS BITS FOR FCB CONSISTING OF 
FC.WAC= 100000 ; SET IF FILE ACCESSED FOR WRITE 
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040000 
020000 
010000 


000036 
000040 
000042 
000044 
000050 


000052 
000054 


000054 
000000 


000000 
000000 
000000 


000400 
001000 
002000 
004000 
010000 
020000 
040000 
100000 
000002 
000003 
000004 
000006 
000010 
000012 


000014 


40000 
20000 
10000 


FC.DIR= 
FC.«CEF= 
FC.FCO= 


F.DREF: -BLKW 
F.DRNM: .BLKW 
F.FEXT: .-BLKW 
F.FVBN: .BLKW 
F.LKL: .~BLKW 


F.WINs: 
F.LGTH: 


e BLKW 


WINDOW 


a} ae =e 


eASECT 


W.ACT: 


W-.BLKS:?: 


W.CTL: -BLKW 


400 
1000 
2000 
4000 
10000 
20000 


WI .RDV= 
WI .WRV= 
WI .EXT= 
WI.LCK= 
WI .DLK= 
WI .PND= 
WI.-EXL= 40000 
WI.WCK= 100000 
W.ITOC:.BLKB 
eBLKB 
W.FCB:.BLKW 
W.TCB: -BLKW 
W.UCB: -BLKW 


W.LKL: -.BLKW 


W.WIN: .BLKW 


Pe Be 
oIF 


rh Re 


‘nc 


ee 


al 


FLIEDFES;7SYSDFE 


=e ~S ~H WH BWH WH WS WH WH WH WH WH 


@=e ~WO ~@ we BF WH WOH WE WH WH VO WH WHE WH WH WH BVO VW WO AQ WH WE 


NB,SYSDF 
NDF ,PSSWND 


e 
g 


SET IF FCB IS IN DIRECTORY LRU 
SET IF DIRECTORY EOF NEEDS UPDATING 
SET IF TRYING TO FORCE DIRECTORY 
CONTIGUOUS 

DIRECTORY EOF BLOCK NUMBER 

1ST WORD OF DIRECTORY NAME 
POINTER TO EXTENSION FCB 

STARTING VBN OF THIS FILE SEGMENT 
POINTER TO LOCKED BLOCK LIST FOR 
FILE 

WINDOW BLOCK LIST FOR THIS FILE 
SIZE IN BYTES OF FCB 


NUMBER OF ACTIVE MAPPING POINTERS 
WHEN NO SECONDARY POOL 

BLOCK SIZE OF SECONDARY POOL SEGMENT 
WHEN SECONDARY POOL 

LOW BYTE = # OF MAP ENTRIES ACTIVE 
HIGH BYTE CONSISTS OF CONTROL BITS 
READ VIRTUAL BLOCK ALLOWED IF SET 
WRITE VIRTUAL BLOCK ALLOWED IF SET 
EXTEND ALLOWED IF SET 

SET IF LOCKED AGAINST SHARED ACCESS 
SET IF DEACCESS LOCK ENABLED 
WINDOW TURN PENDING BIT 

SET IF MANUAL UNLOCK DESIRED 

DATA CHECK ALL WRITES TO FILE 
COUNT OF I/O THROUGH THIS WINDOW 
RESERVED 

FILE CONTROL BLOCK ADDRESS 

TCB ADDRESS OF ACCESSOR 

ORIGINAL UCB ADDRESS OF DEVICE 
POINTER TO LIST OF USERS LOCKED 
BLOCKS 

WINDOW BLOCK LIST LINK WORD 


; IF SYSDF SPECIFIED IN CALL 
; IF SECONDARY POOL WINDOWS NOT 
ALLOWED 


IF SECONDARY POOL WINDOWS ARE NOT ENABLED, THE WINDOW 


7; NON-~SECONDARY POOL WINDOW BLOCK 


BLOCK CONTAINS THE CONTROL INFORMATION AND RETRIEVAL 
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gost, 


000016 


000017 
000017 


000020 
000022 


177774 


POINTERS. 


% @ % @ 


W.VBN: .BLKB 
W.MAP 


W.WISZ:.BLKB 


-e BLKW 
W.RTRV: 
eLlFF 


ee ze BVO WHE WH BH WS 


W.MAP: .BLKW 


W.SLEN: 


@~e@ ~=@ BSE BE VE WS 


ASSUME 


e BLKB 
W.USE: .BLKB 
W.VBN: .BLKB 
W.WISZ:.BLKB 

e BLKW 
W.RTRV: 


e ENDC 


e ENDC 


a 


~e@ we % @ 


~~ @ 


1 


F11DFS,,SYSDF 


HIGH BYTE OF 1ST VBN MAPPED BY WINDOW 
DEFINE LABEL WITH ODD ADDRESS TO 
CATCH BAD REFERENCES 

SIZE IN RTRV PTRS OF WINDOW (7 BITS) 
LOW ORDER WORD OF 1ST VBN MAPPED 
OFFSET TO IST RETRIEVAL POINTER IN 
WINDOW 


~e B26 wWE WO =e Ee % @ 


DUMMY DEFINITION TO PREVENT INCORRECT 


REFERENCE (-4 WHEN ROUNDED "UP" IS A 
very LARGE BLOCK) 


IF WINDOWS IN SECONDARY POOL 


SECONDARY POOL WINDOW CONTROL AND MAPPING BLOCK 
IF SECONDARY POOL WINDOW BLOCKS ARE ENABLED, LUTN2 
POINTS TO A CONTROL BLOCK IN SYSTEM POOL WHICH 
CONTAINS THE FOLLOWING CONTROL FIELDS AND THE MAPPING 
INFORMATION FOR THE SECONDARY POOL WINDOW. 


ADDR TO THE MAPPING PTRS IN SECONDARY 
POOL 
Length of primary pool stub 


w2Ze we 72 e@ 


SECONDARY POOL WINDOW 
IF SECONDARY POOL WINDOW BLOCKS ARE ENABLED, THE 
RETRIEVAL POINTERS ARE MAINTAINED IN SECONDARY POOL 
IN THE FOLLOWING FORMAT. 


W.CTL,O 

1 > NUMBER OF ACTIVE MAPPING POINTERS 

| > STATUS OF BLOCK 

1 * HIGH BYTE OF 1ST VBN MAPPED BY WINDOW 
1 > SIZE IN RTRV PTRS OF WINDOW (7 BITS) 
1 > LOW ORDER WORD OF 1ST VBN MAPPED 


OFFST TO 1ST RTRIEVAL POINTR IN WINDW 


END SECONDARY POOL WINDOW CONDITIONAL 


~ @ 


END SYSDF CONDITIONAL 


~e 


Ar LoS 


000022 
000000 


000000 
000002 
000004 
000005 
000006 
000010 


000000 


FLIDF 


LOCKED BLOCK LIST NODE 


=e@ *2E WE 


eASECT 
-=0 


L.LNK: .BLKW 
L.WI1l:.BLKW 
L.VBl: ~.BLKB 
L.CNT: -.BLKB 
- BLKW 
L.LKSZ: 


ee 
te ~28@ & ae) te 


END OF DEFINITIONS 


=e ~@O@ ~WO 


«PSECT 


$,,SYSDF 


LINK TO NEXT NODE IN LIST 

POINTER TO WINDOW FOR FIRST ENTRY 
HIGH ORDER VBN BYTE 

COUNT FOR ENTRY 

LOW ORDER VBN 
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A.6 GTPKTS 


~®E Be m= @ 


GET I/O PACKET 


MACRO -- AUTOMATES UNIT DETERMINATION -- GTPKTS 


GTPKTS 


eMACRO GTPKTS DEV ,NCTRLR,ADDR,UCBSV,SUC 
CALL SGTPKT 
-lF B <ADDR> 
BCC 65535S$ 
RETURN 
65535S: 
e LFF 
BCS ADDR 
eENDC 
~lF B <UCBSV> 
elF B <SUC> 
MOV R5,S-OWN(R4) 
eENDC 
e LFF 
~LF GT NCTRLR-1 
MOV R5,UCBSV(R3) 
slFE 
MOV R5,UCBSV 
eENDC 
eENDC 
e ENDM 


A-17 


HDRDFS 
A.7 HDRDFS 


; TASK HEADER OFFSET DEFINITIONS 


eASECT 


000000 H.CSP: .BLKW 
000002 H.HDLN: .-BLKW 
000004 H.SMAP:.BLKB 
000005 H.DMAP: .BLKB 
000006 - BLKW 
000010 H.CUIC: .BLKW 
000012 H.DUIC: .BLKW 
000014 H.IPS: .~BLKW 
000016 H.IPC: .BLKW 
000020 H.ISP: .BLKW 
000022 H.ODVA: .BLKW 
000024 H.ODVL: -BLKW 
000026 H.TKVA: .-BLKW 
000030 H.TKVL: .-BLKW 
000032 H.PFVA: .BLKW 
000034 H.FPVA: ._BLKW 
000036 H.RCVA: -BLKW 
000040 H.EFSV: .BLKW 
000042 H.FPSA: .BLKW 
000044 H.WND: .BLKW 
000046 H.DSW: .BLKW 
000050 H.FCS: .~BLKW 
000052 H.FORT: .BLKW 
000054 H.OVLY: .BLKW 
000056 H.VEXT: .BLKW 
000060 H.SPRI:.BLKB 
000061 H.NML: .BLKB 
000062 H.RRVA: .BLKW 
000064 H.X25: .BLKB 
000065 -BLKB 
000066 - BLKW 
000072 H.GARD: .-BLKW 
000074 H.NLUN: .BLKW 
000076 H.LUN: .BLKW 


*CURRENT STACK POINTER 
*HEADER LENGTH IN BYTES 

*>SUPERVISOR D SPACE OVERMAP MASK 

*>USER D SPACE OVERMAP MASK 

° RESERVED 

*CURRENT TASK UIC 

>DEFAULT TASK UIC 

* INITIAL PROCESSOR STATUS WORD (PS) 

e INITIAL PROGRAM COUNTER (PC) 

* INITIAL STACK POINTER (SP) 

ODT SST VECTOR ADDRESS 

ODT SST VECTOR LENGTH 

°TASK SST VECTOR ADDRESS 

°TASK SST VECTOR LENGTH 

>POWER FAIL AST CONTROL BLOCK ADDRESS 
*>FLOATING POINT AST CONTROL BLOCK ADDR 
*RECEIVE AST CONTROL BLOCK ADDRESS 
>EVENT FLAG ADDRESS SAVE ADDRESS 
*POINTR TO FLOATING POINT/EAE SAVE AREA 
*POINTER TO NUMBER OF WINDOW BLOCKS 
*TASK DIRECTIVE STATUS WORD 

°-FCS IMPURE POINTER 

eFORTRAN IMPURE POINTER 

eOVERLAY IMPURE POINTER 

e>WORK AREA EXTENSION VECTOR POINTER 
*PRIORITY DIFFERENCE FOR SWAPPING 
*>NETWORK MAILBOX LUN 

*RECEIVE BY REF AST CONTROL BLOCK ADDR 
*FOR USE BY X25 SOFTWARE 

°>5 RESERVED BYTES 


*POINTER TO HEADER GUARD WORD 
>NUMBER OF LUN'S 
*START OF LOGICAL UNIT TABLE 


EN ee ee ee ee ee ee ee ee eee ee 


-- 
LENGTH OF FLOATING POINT SAVE AREA 


=O We ~™ @ 


H.FPSL=25.*2 


-- 
WINDOW BLOCK OFFSETS 


® 
g 
e 
e 
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10090 
fen, 
wf 


000000 
000002 
000004 
000006 
000010 
000012 
000014 
000015 
000016 
000020 


W.BPCB: .BLKW 
W.BLVR: -BLKW 
W.BHVR: -.BLKW 
W.BATT: -.BLKW 
W.BSIZ:.BLKW 
W.BOFF: .BLKW 
W.BFPD:.BLKB 
W.BNPD: -.BLKB 
W.BLPD: -.BLKW 
W.BLGH: 


be ped pe pe ped RP 


BIT DEFINITION FOR W. 


~e @6@ BSP 


WB .NBP=20 


WB .BPS=40 


ePSECT 


HDRDFS 


;PARTITION CONTROL BLOCK ADDRESS 

;LOW VIRTUAL ADDRESS LIMIT 

;HIGH VIRTUAL ADDRESS LIMIT 

; ADDRESS OF ATTACHMENT DESCRIPTOR 
;SIZE OF WINDOW IN 32W BLOCKS 
;PHYSICAL MEMORY OFFSET IN 32W BLOCKS 
;FIRST PDR ADDRESS 

;NUMBER OF PDR’S TO MAP 

;CONTENTS OF LAST PDR 

; LENGTH OF WINDOW DESCRIPTOR 


BLPD 


>CACHE BYPASS IS NOT DESIRED FOR THIS 
; WINDOW 

; ALWAYS BYPASS THE CACHE FOR THIS 

; WINDOW 
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HWDDFS$ ,L,B,SYSDEF 
A.8 HWDDFS$,L,B,SYSDEF 


7 HARDWARE REGISTER ADDRESSES AND STATUS CODES 


;ADDRESS OF PDP-11/70 MEMORY PARITY REGISTER 
;ADDRESS OF FIRST MEMORY PARITY REGISTER 
7; PROGRAMMED INTERRUPT REQUEST REGISTER 


MPCSR=177746 
MPAR=172100 
PTROQ=177772 


PRO=0 ; PROCESSOR PRIORITY O 

PR1=40 ;PROCESSOR PRIORITY 1 

PR4=200 ; PROCESSOR PRIORITY 4 

PR5=240 *PROCESSOR PRIORITY 5 

PR6=300 ;PROCESSOR PRIORITY 6 

PR7=340 *PROCESSOR PRIORITY 7 

PS=177776 PROCESSOR STATUS WORD 

SWR=177570 ;CONSOLE SWITCH AND DISPLAY REGISTER 
TPS=177564 ; CONSOLE TERMINAL PRINTER STATUS REGISTER 
-/- 


=e Be =@e 


AC=177302 
MQ=177304 
SC=177310 


~=e BO = @ 


elF DF 


e ENDC 


ES SEAE 


EXTENDED ARITHMETIC ELEMENT REGISTERS 


; ACCUMULATOR 
;MULTIPLIER-QUOTIENT 
;SHIFT COUNT 


CRESET KINAR,172340 


KINARO 
KINARIL 


KINAR2 = 


KINAR3 
KINAR4 
KINARS5 
KINAR6 
KINAR/ 


CRESET KINDR,172300 


KINDRO 
KINDRI 
KINDR2 


MEMORY MANAGEMENT HARDWARE REGISTERS AND STATUS CODES 


;KERNEL I PAR'S 
172340 
172342 
172344 
172346 
172350 
TI235.2 
172354 
172356 


KERNEL I PDR‘'S 
172300 
172302 
172304 


Hou tl se 
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CRESET 


CRESET 


CRESET 


CRESET 


CRESET 


CRESET 


HWDDFS ,L,B,SYSDEF 


KINDR3 
KINDR4 
KINDR5 
KINDR6 
KINDR7 


KDSAR, 172360 


KDSARO 
KDSARI 
KDSAR2 
KDSAR3 
KDSAR4 
KDSAR5 
KDSAR6 
KDSAR7 


KDSDR, 172320 


KDSDRO 
KDSDRI1 
KDSDR2 
KDSDR3 
KDSDR4 
KDSDR5 
KDSDR6 
KDSDR7/ 


SISAR,172240 


SISARO 
SISARI 
SISAR2 
SISAR3 
SISAR4 
SISAR5 
SISAR6 
SISAR7 


SISDR,172200 


SISDRO 
SISDRI1 
SISDR2 
SISDR3 
SISDR4 
SISDR5 
SISDR6 
SISDR7 


SDSAR,172260 


SDSARO 
SDSARI 
SDSAR2 
SDSAR3 
SDSAR4 
SDSAR5 
SDSAR6 
SDSAR7 


SDSDR,172220 


bu ud ub ud uo uw bese tt Hou t t Ut W tse HUW tt UU Wd Ue tse Hon tt wt th uo tt tse HW dt ua 


we HO on ot Wd ou ou wou sxe 


172306 
LIZS 20 
ay ae Bh 
172314 
LI ZIL6 


KERNEL D PAR'S 


172360 
172362 
172364 
172366 
172370 
TI2372 
172374 
172376 


KERNEL D PDR'S 


172320 
LIZS 22 
172324 
172326 
172330 
LIZ3 32 
172334 
172336 


SUPERVISOR I PAR'’S 


172240 
172242 
172244 
172246 
172250 
LiZeoe 
172254 
172256 


SUPERVISOR I PDR'S 


172200 
172202 
172204 
Ld 2206 
172210 
LI 2222 
172214 
Lig2 6 


SUPERVISOR D PAR'S 


172260 
172262 
172264 
172266 
BIZ 270 
LI2272 
172274 
172276 


SUPERVISOR D PDR'S 
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CRESET 


CRESET 


CRESET 


CRESET 


oIF 


HWDDFS ,L,B,SYSDEF 


SDSDRO 
SDSDRI 
SDSDR2 
SDSDR3 
SDSDR4 
SDSDR5 
SDSDR6 
SDSDR7 


UINAR,177640 


UINARO 
UINARI 
UINAR2 
UINAR3 
UINAR4 
UINARS5 
UINAR6 
UINAR7 


UINDR,177600 


UINDRO 
UINDRI1 
UINDR2 
UINDR3 
UINDR4 
UINDR5 
UINDR6 
UINDR7 


UDSAR, 177660 


UDSARO 
UDSARI1 
UDSAR2 
UDSAR3 
UDSAR4 
UDSARS 
UDSAR6 
UDSAR7 


UDSDR,177620 


DE 


UDSDRO 
UDSDRI 
UDSDR2 
UDSDR3 
UDSDR4 
UDSDR5 
UDSDR6 
UDSDR7 


KSSDAS 


CRESET KISAR,172360 


KISARO 
KISARI 
KISAR2 


Hout wt wee UU HW Wt Wt WW tse HU th ot Wot Ww ese WU UW nt WW WoW tse tf WoW uw Wb te de 


>KERNEL I/D 


;KERNEL I PAR‘S 


L72220 
LIZZ 22 
172224 
172226 
172230 
PiZ252 
172234 
172236 


USER I PAR'S 


177640 
177642 
177644 
177646 
177650 
177652 
177654 
I7 7655 


USER I PDR’S 


177600 
177602 
177604 
177606 
177610 
LTTOL2 
177614 
177616 


USER D PAR'S 


177660 
177662 
177664 
177666 
177670 
177672 
177674 
177676 


USER D PDR‘S 


177620 
177622 
177624 
177626 
177630 
LPTO32 
177634 
177636 


172360 
172362 
172364 
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KISAR3 = 172366 
KISAR4 = 172370 
KISAR5 = 172372 
KISAR6 = 172374 
KISAR7 = 172376 
CRESET KISDR,172320 *>KERNEL I PDR'S 
KISDRO = 172320 
KISDR1 = 172322 
KISDR2 = 172324 
KISDR3 = 172326 
KISDR4 = 172330 
KISDR5 = 172332 
KISDR6 = 172334 
KISDR7 = 172336 
~ LFF *>NO KERNEL I/D 
CRESET KISAR,172340 *KERNEL I PAR'S 
KISARO = 172340 
KISAR1 = 172342 
KISAR2 = 172344 
KISAR3 = 172346 
KISAR4 = 172350 
KISAR5 = 172352 
KISAR6 = 172354 
KISAR7 = 172356 
CRESET KISDR,172300 *>KERNEL I PDR'S 
KISDRO = 172300 
KISDR1 = 172302 
KISDR2 = 172304 
KISDR3 = 172306 
KISDR4 = 172310 
KISDR5 = 172312 
KISDR6 = 172314 
KISDR7 = 172316 
~ENDC °DF KSSDAS 
~IF DF USSDAS ;USER I/D 
CRESET UISAR,177660 *USER I PAR'S 
UISARO = 177660 
UISAR1 = 177662 
UISAR2 = 177664 
UISAR3 = 177666 
UISAR4 = 177670 
UISAR5 = 177672 
UISAR6 = 177674 
UISAR7 = 177676 
CRESET UISDR,177620 s>USER I PDR'S 
= 177620 


HWDDFS$ ,L,B,SYSDEF 


UISDRO 
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HWDDFS ,L,B,SYSDEF 


UISDR1 = 177622 
UISDR2 = 177624 
UISDR3 = 177626 
UISDR4 = 177630 
UISDR5 = 177632 
UISDR6 = 177634 
UISDR7 = 177636 
~ LFF eNO USER I/D 
CRESET UISAR,177640 USER I PAR'S 
UISARO = 177640 
UISAR1 = 177642 
UISAR2 = 177644 
UISAR3 = 177646 
UISAR4 = 177650 
UISAR5 = 177652 
UISAR6 = 177654 
UISAR7 = 177656 
CRESET UISDR,177600 e-USER I PDR'S 
UISDRO = 177600 
UISDR1 = 177602 
UISDR2 = 177604 
UISDR3 = 177606 
UISDR4 = 177610 
UISDR5 = 177612 
UISDR6 = 177614 
UISDR7 = 177616 
eENDC >DF USSDAS 
UBMPR=170200 *>UNIBUS MAPPING REGISTER 0 
CMODE=140000 CURRENT MODE FIELD OF PS WORD 
PMODE=30000 *PREVIOUS MODE FIELD OF PS WORD 
CSMODE=40000 CURRENT MODE = SUPERVISOR PS WORD BITS 
PSMODE=10000 *PREVIOUS MODE = SUPERVISOR PS WORD BITS 
SRO=177572 SEGMENT STATUS REGISTER 0 
SR3=172516 SEGMENT STATUS REGISTER 3 
CPUERR=177766 eCPU ERROR REGISTER 
MEMERR=177744 e>MEMORY SYSTEM ERROR REGISTER 
MEMCTL=177746 eMEMORY CONTROL REGISTER 


+ 
DEFINE THE LOCATIONS USED IN THE NON-VOLATIL RAM (NVR) 
FOR P/OS SYSTEMS 


@™6 BEG BQ WE 


N.KEY=173054 ;NUMBER OF KEYS PRESSED 
N.UPT=173064 ;UPTIME IN MINUTES 
N.DZA=173074 ;NUMBER OF I/OS DONE ON THE DZ 
N.DWA=173104 ;NUMBER OF I/OS DONE ON THE DW 
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HWDDFS ,L,B,SYSDEF 


N.DAY=173114 ° 
N .MON=173116 Bog ee 
N.YEA=173120 ° 


of 
FEATURE SYMBOL DEFINITIONS 


Se se wa @ 


FE.EXT=1  722-BIT EXTENDED MEMORY SUPPORT 

FE .MUP=2 ;MULTI-USER PROTECTION SUPPORT 

FE .EXV=4 ;EXECUTIVE IS SUPPORTED TO 20K 

FE.DRV=10 ; LOADABLE DRIVER SUPPORT 

FE.PLA=20 7;PLAS SUPPORT 

FE .CAL=40 7; DYNAMIC CHECKPOINT SPACE ALLOCATION 
FE.PKT=100 *;PREALLOCATION OF I/O PACKETS 
FE.EXP=200 7;EXTEND TASK DIRECTIVE SUPPORTED 
FE.LST=400 PROCESSOR IS AN LSI-11 

FE.OFF=1000 7 PARENT/OFFSPRING TASKING SUPPORTED 
FE .FDT=2000 ;FULL DUPLEX TERMINAL DRIVER SUPPORTED 
FE .X25=4000 7Xe25 CEX IS LOADED 

FE .DYM=10000 7; DYNAMIC MEMORY ALLOCATION SUPPORTED 
FE .CEX=20000 7;COM EXEC IS LOADED 

FE .MXT=40000 ;MCR EXIT AFTER EACH COMMAND MODE 

FE .NLG=100000 *;LOGINS DISABLED - MULTI-USER SUPPORT 
1. 


@~e we wm @ 


FEATURE MASK DEFINITIONS (SECOND WORD) 


F2.DAS=1 *>KERNEL DATA SPACE SUPPORTED 
F2.LIB=2 SUPERVISOR MODE LIBRARIES SUPPORTED 

F2.MPp=4 SYSTEM SUPPORTS MULTIPROCESSING 
F2.EVT=10 SYSTEM SUPPORTS EVENT TRACE FEATURE 
F2.ACN=20 SYSTEM SUPPORTS CPU ACCOUNTING 

F2.SDW=40 >SYSTEM SUPPORTS SHADOW RECORDING 
F2.POL=100 «SYSTEM SUPPORTS SECONDARY POOLS 
F2.WND=200 SYSTEM SUPPORTS SECONDARY POOL FILE WINDOWS 
F2.DPR=400 SYSTEM HAS A SEPARATE DIRECTIVE PARTITION 
F2.IRR=1000 © INSTALL, RUN, AND REMOVE SUPPORT 
F2.GGF=2000 GROUP GLOBAL EVENT FLAG SUPPORT 
F2.RAS=4000 e-RECEIVE/SEND DATA PACKET SUPPORT 

F2 .AHR=10000 ALT. HEADER REFRESH AREA SUPPORT 
F2.RBN=20000 >ROUND ROBIN SCHEDULING SUPPORT 
F2.SWP=40000 EXECUTIVE LEVEL DISK SWAPPING SUPPORT 
F2.STP=100000 EVENT FLAG MASK IS IN THE TCB(1=YES) 

of 


=e WO wa @ 


THIRD FEATURE MASK SYMBOL DEFINITIONS 
F3.CRA=1 SYSTEM SPONTANEOUSLY CRASHED (1=YES) 
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F3.XCR=2 
F3.EIS=4 
F3.STM=10 
F3.UDS=20 
F3.PRO=40 
F3.XHR=100 
F3.AST=200 
F3.11S=400 
F3.CLI=1000 
F3.TCM=2000 
F3.PMN=4000 
F3.WAT=10000 
F3.RLK=20000 
F3.SHF=40000 


--- 


Se @wWSE =e 


F4.CXD=1 
F4.XT=2 
F4.ERL=4 
F4.PTY=10 
F4.DVN=20 
F4.LCD=40 
F4.NIM=100 


of 


=e =E@ BBWS VSB or} 


HF .UBM=1 
HF .EIS=2 
HF .QOB=4 
HF ..CIS=200 


HF .FPP=100000 


rs 


H2.NVR=1 
H2.INV=2 
H2.CLK=4 
H2.ITF=10 


H2.BRG=100000 


FOURTH FEATURE 


HWDDFS ,L,B,SYSDEF 


*SYSTEM CRASHED FROM XDT (1=YES) 

SYSTEM REQUIRES EXTENDED INSTRUCTION SET 
>SYSTEM HAS SET SYSTEM TIME DIRECTIVE 
*SYSTEM SUPPORTS USER DATA SPACE 

*>SYSTEM SUPPORTS SEC. POOL PROTO TCBS 
>SYSTEM SUPPORTS EXTERNAL TASK HEADERS 
SYSTEM HAS AST SUPPORT 

*>RSX-11S SYSTEM 

*>MULTIPLE CLI SUPPORT 

SYSTEM HAS SEPARATE TERMINAL DRIVER POOL 
*>SYSTEM SUPPORTS POOL MONITORING 

*>SYSTEM HAS WATCHDOG TIMER SUPPORT 
SYSTEM SUPPORTS RMS RECORD LOCKING 
SYSTEM SUPPORTS SHUFFLER TASK 


MASK BITS 


;COMM EXEC IS DEALLOCATED (NON-I/D ONLY) 


;SYSTEM IS AN PROFESSIONAL SYSTEM (1=YES) 


SYSTEM SUPPORTS ERROR LOGGING (1=YES) 


;SYSTEM SUPPORTS PARITY MEMORY (1=YES) 
;SYSTEM SUPPORTS DECIMAL VERSIONS (1=YES) 
;SYSTEM SUPPORTS LOADABLE CRASH (1=YES) 
;SYSTEM SUPPORTS DELETED TASK IMAGES (1=YES) 


HARDWARE FEATURE MASK BIT DEFINITIONS 


HF.CIS,HF.FPP DEFINED AS SIGN BITS FOR RUN TIME SPEED 


*PROCESSOR HAS A UNIBUS MAP (1=YES) 

*PROCESSOR HAS EXTENDED INSTRUCION SET 
SYSTEM HAS A QBUS (1=YES) 
>PROCESSOR SUPPORTS COMMERCIAL INSTRUCTION SET 
°(1=PROC. HAS NO FLOATING POINT UNIT) 


SECOND HARDWARE FEATURE MASK BIT DEFINITIONS 
THIS WORD IS RESERVED FOR PROFESSIONAL SERIES HARDWARE FEATURES 


*PRO NON-VOLATILE RAM PRESENT (1=YES) 
*>NON-VOLATILE RAM IS INVALID (1=YES) 
*PRO CLOCK IS PRESENT (1=YES) 
* INVALID TIME FORMAT IN NON-VOLATILE RAM 
; (1=YES) 
>PRO BRIDGE MODULE PRESENT (1=YES) 
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ote 


CDA. 


=e =e BE WHE WS WH WE WH WS 


SF.STD=1 
SF.PGN=2 


MULTIPROCESSOR 


Se ~@2E =~ 6 


MP .CRH=100000 
MP.PWF=40000 
MP.RSM=20000 
MP .NOP=10000 
MP.STP=4 
MP.INT=7777 


e MACRO 
e ENDM © 
e ENDM 


HWDDFS ,L,B,SYSDEF 


SYSGEN FEATURE SELECTIONS MASK. THIS IS INTENDED TO RECORD IN A 

BIT MASK THE CHOICES THE USER HAS MADE AT SYSGEN TIME. FEATURES WILL 
BE LISTED HERE WHEN THEY ARE BEING RECORDED FOR OUR INFORMATIONAL 
PURPOSES ONLY. THEY CANNOT BE TESTED LIKE BITS IN THE FEATURE MASK 
SINCE THIS ONLY EXISTS IN THE RSX11M.STB FILE. NO BITS IN MEMORY 

ARE USED. THEY ARE ONLY INTENDED TO BE PRINTED FROM THE STB FILE BY 


7;STANDARD EXEC SELECTED 
;SYSTEM WAS PRE-GENERATED (EX. RLO2/RC25 
; SYSTEM) 


STATUS TABLE DEFINITIONS (TEMPORARY) 


;CRASH PROCESSOR IMMEDIATELY 

; POWERFAIL ON ONE CPU 

*;RESET INTERRUPT MASKS 

*NOP FUNCTION FOR TRANSMISSION CHECK 
*STOP PROCESSOR IN ORDERLY FASHION 

*>BIC MASK FOR INTERRUPT LVL FUNCTIONS 


HWDDFS X,Y,Z 
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FIIDFS,,SYSDF 


A.9 F11DFS$,,SYSDF 


INTERRUPT SAVE GENERATION FOR NON-ERROR LOGGING DEVICES -- INTSVS 


Se =e BW 


»MACRO INTSVS DEV,PRI,NCTRLR, PSWSV,UCBSV 
GTUCBS$ UCBSV,NCTRLR,DEV 
e ENDM 


GENERATE CODE TO LOAD UCB ADDRESS INTO R5 -- CALLED 
ONLY BY INTSVS, AND TTSETS (IN TTDRV). 


=e @H WHE VW 


»~MACRO GTUCBS UCBSV,NCTRLR,DEV 
-IF NB <UCBSV> 
IF GT NCTRLR-1 


MOV UCBSV(R4),R5 

olFF 

MOV UCBSV,R5 

eENDC 

olFF 

MOV 'DEV'CTB,R5 ;7;7GET ADDRESS OF KRB TABLE IN CTB 
ADD R4,R5 ;77;ADD CONTROLLER INDEX 

MOV (R5),R5 7;77;GET KRB ADDRESS FROM CTB 
MOV K.OWN(R5),R5 7;7;7;RETRIEVE OWNERS UCB ADDRESS 
e ENDC 

e ENDM 
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ITBDFS ;,SYSDF 


A.10 ITBDFS,,SYSDF 


ote 


INTERRUPT TRANSFER BLOCK (ITB) OFFSET DEFINITIONS 


wg @~e We a @ 


~1IF DF ASSTRP 


-MCALL PKTDFS 


PKTDFS DEFINE AST BLOCK OFFSETS 


™=e 


e ENDC 


eASECT 
-=0 


000000 XeLNK: e BLKW i LINK WORD FOR ITB LIST STARTNG IN 


are i Ges ' 
000002 XeJSR: JSR R5,@#0 ; CALL SINTSC 
000006 X-PSW: eBLKB 1 * LOW BYTE OF PSW FOR ISR 
000007 eBLKB 1 ; UNUSED 
O00010 Xe ISR: e BLKW 1 * ISR ENTRY POINT (APR5 MAPPING) 
000012 Xe FORK: > FORK BLOCK 
000012 e BLKW 1 ° THREAD WORD 
000014 » BLKW Pe * FORK PC 
000016 e BLKW 1 * SAVED R5 
000020 e BLKW 1 >: SAVED R4 


~LF DF MSSMGE 


XeREL: .~BLKW a RELOCATION BASE FOR APR5 


~e 


eENDC 


000022 XeDSI:s: .BLKW 1 
000024 Xo CBs e BLKW a3 


ADDRESS OF DIS.INT. ROUTINE 
TCB ADDRESS OF OWNING TASK 


m~ @ %& @ 


sth NB: SYSDE 


~IF DF ASSTRP 


»BLKW 1 - A.DOSR FOR AST BLOCK 
X.AST: .BLKB A.PRM : AST BLOCK 
»ENDC 


VECTOR ADDRESS (IF AST SUPPORT, 

THIS IS FIRST AND ONLY AST PARAMETER) 
SAVED VECTOR PC 

LENGTH IN BYTES OF ITB 


000026 XeVEC: e BLKW 1 


000030 XeVPC: - BLKW 1 
000032 Xe LEN: 


@2=e ~O ~O DWE 
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ITBDFS ,,SYSDF 


eENDC 


e-PSECT 


A-30. 


KRBDFS,,SYSDF 


Aell KRBDFS,,SYSDF 


\ 


CONTROLLER REQUEST BLOCK (KRB) 


== 


THE CONTROLLER REQUEST BLOCK DEFINES THE ENVIRONMENT OF A 
DEVICE CONTROLLER. ONE KRB EXISTS FOR EVERY DEVICE CONTROLLER 
IN A P/OS SYSTEM. THE KRB CONTAINS CERTAIN DEVICE STATUS 
INCLUDING THE CSR (FIRST DEVICE REGISTER, VECTOR ADDRESS, 
INTERUPT CONTROLLER ‘A’ CSR AND THE SLOT NUMBER FOR THE 
CONTROLLER. 


@g Be 6 ~2e Be %G@ Be =e BE ®% @ 


eASECT 
-=177764 
177764 KePRM: .BLKW u ;DEVICE DEPENDANT PARAMETER WORD 
177766 Ke-ICSR: .~BLKW ti ; INTERRUPT 'A’ CONTROLLER CSR (ADD 4 
;FOR ICSR 'B' IF APPROPRIATE TO DEVICE) 
177770 K.SLT: .BLKB 1 ;SLOT NUMBER 
LTT bad -BLKB a! 7 RESERVED 
LUE Ea KePRI: .BLKB iL ;CONTROLLER PRIORITY 
Litto K.-VCT: .BLKB a 7; INTERRUPT VECTOR ADDRESS 
177774 K.CON: .BLKB LE ;CONTROLLER INDEX WITHIN THE SYSTEM 
LTT IS K.IOC: .BLKB 1 ;CONTROLLER I/O COUNT 
177776 K.STS: .BLKW 1 CONTROLLER STATUS 
000000 KeCSR: .BLKW 1 ;ADDRESS OF CONTROL STATUS REGISTER 
; NOTE: K.CSR MUST BE THE ZERO OFFSET! 
000002 K.OFF: .«BLKW 1 ;OFFSET TO UCB/UMR/RHBAE TABLE 
000004 KeHPU: .BLKB 1 ;HIGHEST PHYSICAL UNIT NUMBER 
000005 «BLKB 1 ;UNUSED BYTE 
000006 Ke-OWN: .BLKW 1 ;OWNER OF CONTROLLER 
000010 KeCRO: .«BLKW 2 ;CONTROLLER REQUEST QUEUE 
000014 KeURM: .BLKW 1 7;RESERVED FOR FUTURE USE 
000016 KeFRK: .BLKW 1 7POSSIBLE KRB FORK BLOCK 
Hees 
; OFFSETS FOR THE KRB EXTENSION REACHED BY ADDING (K.OFF) TO 
; THE STARTING ADDRESS OF THE KRB. 
; WHEN ONE ADDS (K.OFF) TO THE KRB ADDRESS, IT YIELDS AN 
; ADDRESS WHICH POINTS TO HERE. 
000000 KE-UCB: .~BLKW 1 >OFFSET TO UCB TABLE (IF KS.UCB SET) 


-. 


»PSECT 


> CONTROLLER REQUEST BLOCK (KRB) STATUS BIT DEFINITIONS 


Rost 


000001 
000002 
000004 
000010 
000020 


000040 
000100 
000200 
000400 


001000 


002000 


000022 


177756 
177760 
177761 
hI Be a Bl 2 
177763 
177764 
177765 
177766 
177770 
LITE 2 
177774 
LV ITTS 
177776 


g 


KS .OFL=1 
KS -MOF=2 
KS .UOP=4 
KS .MBC=10 
KS .SDX=20 


KS .POE=40 
KS .UCB=100 
KS .DIP=200 
KS .PDF=400 


KS .EXT=1000 


KS .<SLO=2000 


-- 


S26 BG BBWS 


eASECT 
o=177756 
SeICSR: -BLKW 
S.SLT: .BLKB 1 

e BLKB 
SePRI: .~BLKB 
S.VCT: .~BLKB 
S-eCON: .~BLKB 

- BLKB 

e BLKW 
S.-CSR: .~BLKW 

e BLKW 

eBLKB 

e BLKB 
5S-OWN: .~BLKW 
-. 


—=@ @=@ =e WE wa @ we WS 


eASECT 


bel 


ee ee ee 


KRBDFS$ , ,SYSDF 


*CONTROLLER OFFLINE (1=YES) 

*CONTROLLER MARKED FOR OFFLINE (1=YES) 

SUPPORTS OVERLAPPED OPERATION (1=YES) 

° (RESERVED) 

SEEKS ALLOWED DURING DATA XFERS 

: (1=YES) 

*PARALLEL OPERATION ENABLED (1=YES) 

UCB TABLE PRESENT (1=YES) 

*DATA TRANSFER IN PROGRESS (1=YES) 

*PRIVILEGED DIAGNOSTIC FUNCTIONS ONLY 
(1=YES) 

EXTENDED 22-BIT UNIBUS CONTROLLER 
(1=YES) 

CONTROLLER IS SLOW COMING ONLINE 
(1=YES) 


% @ B26 26 ~®O DWE 


DEFINE THE CONTIGUOUS SCB OFFSETS 


; INTERRUPT ‘'A‘ CONTROLLER CSR 
;SLOT NUMBER 

; RESERVED 

; CONTROLLER PRIORITY 

7; INTERRUPT VECTOR ADDRESS 
;CONTROLLER INDEX 


;CONTROL AND STATUS REGISTER 


;DISTRIBUTED CNTBL 


SUBCONTROLLER REQUEST BLOCK (KRB1) 


THE SUBCONTROLLER REQUEST BLOCK DEFINES THE ENVIRONMENT OF 
A DEVICE SUBCONTROLLER. 
D 


EXACTLY ONE KRB1 EXISTS FOR EVERY 


EVICE SUBCONTROLLER IN AN RSX-11M+ SYSTEM. 
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177774 
LT TTS 
177776 
000000 


000002 
000004 
000010 


KRBDFS$ , ,SYSDF 


K1.CON: .-BLKB 

e BLKB 
K1.STS: .-.BLKW 
K1.MAS: .BLKW 
; NOTE: K1.MAS MUST BE 


r 
g 


ee 


K1l.OWN: ._BLKW 1 
K1.CRO:.BLKW 2 
K1.UCB: 

e-PSECT 


;SUBCONTROLLER INDEX WITHIN THE SYSTEM 
;UNUSED BYTE 

; SUBCONTROLLER STATUS 

7;UCB ADDRESS OF THE MASTER UNIT 


THE ZERO OFFSET 
;OWNER OF SUBCONTROLLER 


>SUBCONTROLLER REQUEST QUEUE 
START OF THE UCB TABLE (IF ANY) 
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000000 
000002 
000004 
000010 
000012 
000014 


000016 
000016 
000020 
000024 
000030 
000032 


000034 


000042 
000043 


000044 


000000 
000002 
000003 


PCBDFS,,SYSDF 


P.WAIT: 


P.STAT: 


P.ST2: 


P.HDLN: 


P«iOCe 
SSS=. 


P.RRMs: 


2=$S$$ 


P.LGTH=. 


of 


Aur © 
sWZ2 
Qe 


rd to tO e =O BU We 


eASECT 


e BLKW 
e BLKW 
- BLKW 
e BLKW 
e BLKW 
e BLKW 


e BLKW 
» BLKW 
e BLKW 
e BLKW 
e BLKW 


e BLKW 


e BLKB 
e BLKB 


- BLKW 


eIF NDF 


e ENDC 


olTF NB 


. ENDC 


» BLKW 
»BLKB 
»BLKB 


PCBDFS$, ,SYSDF 


; MAIN PARTITION PCB 


*LINK TO NEXT MAIN PARTITION PCB 
° (UNUSED) 

*PARTITION NAME IN RAD50 

*POINTER TO FIRST SUBPARTITION 
*POINTER TO SELF 

STARTING PHYSICAL ADDRESS IN 32W 
* BLOCKS 


ee Oe 


a SIZE OF PARTITION IN 32W BLOCKS 
2 *>PARTITION WAIT QUEUE LISTHEAD 

2 - (UNUSED) 

1 *>PARTITION STATUS FLAGS 

ti >STATUS EXTENSION FOR COMMON AND MAIN 


°*PCB'S 
3 ° (UNUSED) 
1 SIZE OF EXTERNAL HEADER IN 32W BLOCKS 
a ;PARTITION I/O COUNT 
1 *REQUIRED RUN MASK 
MSSPRO 
SYSDF 


*PARTITION CONTROL BLOCK LENGTH 


TASK REGION PCB 


1 ,;UTILITY LINK WORD 
1 ;PRIORITY OF PARTITION 
1 ;RESIDENT MAPPED TASKS COUNT 
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000004 
000010 
000012 
000014 
000016 
000016 
000020 
000022 
000024 
000026 
000030 
000032 
000034 
000036 


000042 
000043 


000044 


000000 
000002 
000003 
000004 
000010 


000012 | 


000014 
000016 
000016 
000020 
000022 
000024 
000026 
000030 
000032 


000034 


P.NAM: 
P.SUB: 


P.MAIN: 


P.REL: 


P.BLKS: 
PeolZes 


eSWSZ: 
P.DPCB: 


P.TCB: 


P.STAT: 


P.HDR: 


P.ATT: 


P.HDLN: 


P.IOC: 


000044 


e BLKW 
- BLKW 
e BLKW 
e BLKW 


e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
- BLKW 
e BLKW 
e BLKW 
e BLKW 


eBLKB 
e BLKB 


P.RRM: -BLKW 


-1F NDF MSSPRO 


2=$$$ 


eENDC 


-- 


=0 


© ze ~“G WE 


P.LNKs: 
P.PRI: 


P.RMCTs: 


P .NAM: 
P.SUB: 


P.MAIN: 


P.REL: 


P.BLKS: 
P.SIZE: 
P.CBDL: 
P.SWSZ: 
P«DPCBs 


P.OWN: 


P.STAT: 


P.ST2: 


P2PROS 


COMMON REGION 


e BLKW 
-BLKB 
e BLKB 
e BLKW 
e BLKW 
e BLKW 
e BLKW 


e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 


e BLKW 


HH het KY ND 


ROR Re ee 


fm 


PCB 


el ee ee NO el ood a 


feed fet fat ed bd bed Ps 


owed 


PCBDFS, ,SYSDF 


;PARTITION NAME IN RAD50 

;POINTER TO NEXT SUBPARTITION 
;POINTER TO MAIN PARTITION . 
;STARTING PHYSICAL ADDR IN 32W BLOCKS 


SIZE OF PARTITION IN 32W BLOCKS 
- (UNUSED) 

*PARTITION SWAP SIZE 

*CHECKPOINT ALLOCATION PCB 

*TCB ADDRESS OF OWNER TASK 
*PARTITION STATUS FLAGS 

*POINTER TO HEADER CONTROL BLOCK 
° (UNUSED) 

*ATTACHMENT DESCRIPTOR LISTHEAD 


7;SIZE OF EXTERNAL HEADER IN 32W BLOCKS 
;PARTITION I/O COUNT 


SS$S=. 


7;REQUIRED RUN MASK 


;UTILITY LINK WORD 

;PRIORITY OF PARTITION 

;RESIDENT MAPPED TASKS COUNT 
*PARTITION NAME IN RAD50 

;POINTER TO NEXT SUBPARTITION 
*>POINTER TO MAIN PARTITION 

*STARTING PHYSICAL ADDR IN 32W BLOCKS 


eSIZE OF PARTITION IN 32W BLOCKS 
COMMON BLOCK DIRECTORY LINK 
*PARTITION SWAP SIZE 

*POINTER TO DISK PCB 

eOWNING UIC OF. REGION 

PARTITION STATUS FLAGS 

*STATUS EXTNSN FOR COMMON AND MAIN 
*PCB'S 

PROTECTION WORD [ DEWR , DEWR, DEWR, DEWR] 
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000036 


000042 
000043 


000044 


PCBDFS,,SYSDF 


P.ATT: - BLKW 2 ; ATTACHMENT DESCRIPTOR LISTHEAD 
P.HDLN: .BLKB I ,;SIZE OF EXTERNAL HEADER IN 32W BLOCKS 
P.IOC: .BLKB 1 ;PARTITION I/O COUNT 

SS$=. 

P.RRM: .BLKW 1 ; REQUIRED RUN MASK 


-IF NDF MS$PRO 
-=SS$ 
» ENDC 
» PSECT 


+ 
PARTITION STATUS WORD BIT DEFINITIONS 


™~™SH WH a @ 


PS .OUT=100000 >PARTITION IS OUT OF MEMORY(1=YES) 

PS .CKP=40000 *PARTITION CHECKPOINT IN PROGRESS 
-(1=YES) 

PS.CKR=20000 ePARTITION CHECKPOINT IS REQUESTED 
°(1=YES) 

PS .CHK=10000 *PARTITION IS NOT CHECKPOINTABLE 

| e(1L=YES) 

PS.FXD=4000 *PARTITION IS FIXED (1=YES) 

PS .CAF=2000 *>CHECKPOINT SPACE ALLOCATION FAILURE 
> (1=YES) | 

PS.LIO=1000 MARKED BY SHUFFLER FOR LONG I/O 
-(1=YES) 

PS .NSF=400 ;PARTITION IS NOT SHUFFLEABLE (1=YES) 

PS .COM=200 >LIBRARY OR COMMON BLOCK (1=YES) 

PS.LFR=100 LAST LOAD OF REGION FAILED (1=YES) 

PS.PER=40 ePARTIY ERROR OCCURED IN THIS REGION 
°(1=YES) | 

PS.DEL=10 *PARTITION SHOULD BE DELETED WHEN NOT 
ATTACHED (1=YES) 

PS .AST=4 >PARTITION HAS REGION LOAD AST PENDING 

+ 


—™e WOE WE 


REQUIRED RUN MASK 


PR.UBT=100000 ;UNIBUS RUN T 
PR.UBS=40000 ;UNIBUS RUN S 
PR.~UBR=20000 ;UNIBUS RUN R 
PR.-UBP=10000 ;UNIBUS RUN P 
PR.UBN=4000 ,;UNIBUS RUN N 


A-36 


P2.LMA= 


P2.CPC= 
P2.SEC= 
P2.PAR= 
P2.POL= 
P2.CPU= 
P2.PIC= 
P2.RON= 
P2.DRV= 
P2.APR= 


000000 
000002 
000004 
000006 
000010 


000012 
000014 


PCBDFS,,SYSDF 


PR.UBM=2000 eUNIBUS RUN M 
PR.UBL=1000 >UNIBUS RUN 
PR.UBK=400 *UNIBUS RUN K 
PR.UBJ=200 *UNIBUS RUN J 
PR.UBH=100 e-UNIBUS RUN H 
PR.UBF=40 eUNIBUS RUN F 
PR.UBE=20 *UNIBUS RUN E 
PR.CPD=10 *PROCESSOR D 
PR.CPC=4 ;PROCESSOR C 
PR.CPB=2 * PROCESSOR 
PR.CPA=1 *PROCESSOR A 
-- 


STATUS EXTENSION WORD BIT DEFINITIONS 
(THESE BITS CAN ONLY BE EXAMINED IN COMMON OR MAIN 
PCB'S) 


ze VE BWH WH WE 


40000 ;DON'T SHUFFLE,DELETE SPINDLE OR MUTILATE 
;THIS PARTITION (ACTUALLY ON P/OS V1.7 AND V2.0 
;THIS BIT HAS TAKEN ON THE EXACT OPPOSITE 
;MEANING SINCE IT HAS YET TO BE IMPLEMENTED ON 
7;M-PLUS. TEMPORARILY, IT HAS BEEN REDEIFNED TO 
;MEAN "THIS COMMON IS PART OF THE APPL. 
;AND SHOULD BE REMOVED FROM THE SYSTEM (IF 
*>POSSIBLE) WHEN THE APPLICATION EXITS") 


20000 *>CPCR INITIATED CHECKPOINT PENDING 

4000 THIS IS RO SECTION OF MU TASK WITH TCB IN SEC. POOL 
2000 -THE FIXER TASK HAS HANDLED A PARITY ERROR 

1000 SECONDARY POOL PARTITION 

400 *>MULTIPROCESSOR CPU PARTITION 

200 *>POSITION INDEPENDENT LIBRARY OR COMMON (1=YES) 

100 eREAD-ONLY COMMON (1=YES) 

40 *DRIVER COMMON PARTITION (1=YES) 


7 ;STARTING APR NUMBER MASK FOR NON-PIC COMMON 


; CHECKPOINT FILE PCB 


~-ASECT 
-=0 
P.LNK: .BLKW 1 *LINK WORD OF CHECKPOINT FILE PCB'S 
P.UCB: .BLKW 1 *UCB ADDRESS OF CHECKPOINT FILE DEVICE 
P.LBN: .BLKW 1 *HIGH PART OF STARTING LBN 
~ BLKW 1 LOW PART OF STARTING LBN 
P.SUB: .BLKW zh *POINTER TO FIRST CHECKPOINT 
*ALLOCATION PCB 
P.MAIN: .BLKW i] MUST BE 0 (FOR SRLPR1) 
P.REL: .BLKW 1 *CONTAINS O IF FILE IN USE, 1 IF NOT 


7; IN USE 
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000016 


000020 


000000 
000010 


000012 
000014 


000016 


000000 
000002 


000004 
000006 
000010 
000012 
000014 
000016 


000000 
000002 
000003 
000004 
000006 
000010 
000011 


000012 
000014 


PCBDFS, ,SYSDF 


P.SIZE: .BLKW 1 ;SIZE OF CHECKPOINT FILE IN 256W 
; BLOCKS | 
P.DLGH=. ;LENGTH OF ALL DISK PCB'S 
-+- 


=e WE = @ 


CHECKPOINT ALLOCATION PCB 


<=0 
-BLKW 4 ° (UNUSED) 

P.SUB: .BLKW 1 *LINK TO NEXT CHECKPOINT ALLOCATION 
PCB 

P.MAIN: .BLKW ] *>ADDRESS OF CHECKPOINT FILE PCB 

P.REL: .BLKW 1 *-RELATIVE POSITION ,IN FILE IN 256W 
*BLOCKS 

P.SIZE: .BLKW ] SIZE ALLOCATED IN 256W BLOCKS 

-|- 


; COMMON TASK IMAGE FILE PCB 


P.FIDIL: .~BLKW 1 ;FILE ID WORD FOR SAVE 
P.UCB: - BLKW 1 7;UCB ADDRESS OF DEVICE ON WHICH 
;COMMON RESIDES 
P.LBN: e BLKW 1 ;HIGH PART OF STARTING LBN 
e BLKW 1 ;LOW PART OF STARTING LBN 
P.FID2: .~BLKW I ;FILE ID WORD FOR SAVE 
P.MAIN: .~BLKW 1 ;POINTER TO SELF 
P.REL?: e BLKW I 7;ALWAYS CONTAINS A 0 
P.FID3: .~BLKW 1 ;FILE ID WORD FOR SAVE 
-+- 


A.~PCBL: .~BLKW 1 ;PCB ATTACHMENT QUEUE THREAD WORD 

A.PRI: eBLKB HY ;PRIORITY OF ATTACHED TASK 

A.IOC: e BLKB 1 ;I/O COUNT THROUGH THIS DESCRIPTOR 

A.TCB: e BLKW 1 ;TCB ADDRESS OF ATTACHED TASK 

A.TCBL: .~BLKW 1 7;TCB ATTACHMENT QUEUE THREAD WORD 

A.STAT: .BLKB I ;STATUS BYTE 

Ae-MPCT: .BLKB 1 ;MAPPING COUNT OF TASK THRU THIS 
7 DESCRIPTOR 

A.PCB: e BLKW 1 ;PCB ADDRESS OF ATTACHED TASK 

A.LGTH= . ; LENGTH OF ATTACHMENT DESCRIPTOR 

-/- 


™=6@ =O WE 


ATTACHMENT DESCRIPTOR STATUS BYTE BIT DEFINITIONS 
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PCBDFS , ,SYSDF 


~PSECT 

AS .PRO=100 e-A.TCB IS SEC POOL PROTO TCB BIAS (1=YES) 
AS.SBP=20 CACHE BYPASS REQUESTED 

AS.RBP=40 >REQUEST TO NOT BYPASS CACHE 

AS. DEL=10 *>TASK HAS DELETE ACCESS (1=YES) 

AS .EXT=4 *TASK HAS EXTEND ACCESS (1=YES) 

AS .WRT=2 -TASK HAS WRITE ACCESS (1=YES) 

AS .RED=1 *TASK HAS READ ACCESS (1=YES) 
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Ael3 


=e =@ BS BH WE <a @ 


177774 
177776 
000000 
000002 


000004 


000006 
000010 
000012 


PKTDFS 


o=177774 
AeKSR5: 
A.DQSR: 


A.CBL: 


A-eBYT: 


A.AST: 
A.eNPR3: 
AePRM: 


AS .FPA=1 
AS -.RCA=2 
AS .RRA=3 
AS .PEA=4 
AS .REA=5 
AS .PFA=6 
AS .CAA=7 


BLOCK ARE RELIED UPON 


eASECT 


e BLKW 
e BLKW 
e BLKW 
e BLKW 


» BLKW 


» BLKW 
e BLKW 
e BLKW 


AS .TEA=10 


; ABORTER SUBCODES FOR 


ae 


a) 


PKTDFS 


ASYNCHRONOUS SYSTEM TRAP CONTROL BLOCK OFFSET DEFINITIONS 


SOME POSITIONAL DEPENDENCIES BETWEEN THE OCB AND THE AST CONTROL 
IN THE ROUTINE SFINXT IN THE MODULE SYSXT. 


SUBROUTINE KISAR5 BIAS (A.CBL=0) 
*DEQUEUE SUBROUTINE ADDRESS (A.CBL=0) 
*AST QUEUE THREAD WORD _ 

*>LENGTH OF CONTROL BLOCK IN BYTES 

°IF A.CBL = 0, THE AST CONTROL BLOCK IS 
TO BE DEALLOCATED BY THE DEQUEUE 
SUBROUTINE POINTED TO BY A.DQSR 
MAPPED VIA APR 5 VALUE A.KSR5. THIS 
°IS CURRENTLY USED ONLY BY THE FULL 
*DUPLEX TERMINAL DRIVER FOR UNSOLICITED 
eCHARACTER ASTS. IF THE LOW BYTE OF 
e-A.CBL = 0, AND THE HIGH BYTE IS NOT 
e= Q, THE AST CONTROL BLOCK IS A 
SPECIFIED AST, WITH LENGTH, C.LGTH. 
°IF THE HIGH BYTE OF A.CBL=0 

»AND THE LOW BYTE > O, THEN 

>THE LOW BYTE IS THE LENGTH OF THE 
AST CONTROL BLOCK. 

*>IF HIGH BYTE = O AND LOW BYTE IS 
e-NEGATIVE, THEN THE BLOCK IS A KERNEL 
AST BIT 6 IS SET IF SSGFIN SHOULD 
e-NOT BE CALLED PRIOR TO DISPATCHING 
°THE AST, AND THE LOW SIX BITS (5-0) 
*REPRESENT THE INDEX/2 INTO THE 
*>KERNEL AST DISPATCH TABLE (SKATBL) 
>NUMBER OF BYTES TO ALLOCATE ON TASK 
° STACK 

eAST TRAP ADDRESS 

NUMBER OF AST PARAMETERS 

e-FIRST AST PARAMETER 

CODE FOR FLOATING POINT AST 

°CODE FOR RECEIVE DATA AST 

*CODE FOR RECEIVE BY REFERENCE AST 
>CODE FOR PARITY ERROR AST 

*CODE FOR REQUESTED EXIT AST 

CODE FOR POWER FAIL AST 

CODE FOR CLI COMMAND ARRIVAL AST 
CODE FOR TAST EXIT AST 


ABORT AST (AS.REA) TO BE RETURNED ON 
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000000 
000002 
000003 
000004 
000006 
000010 
000012 
000014 
000016 
000020 
000022 
000024 
000026 
000042 
000044 


000050 


; USER'S STACK 


AB.NPV=1 
AB.TYP=2 


A.PLGH=70 
A.DUCB=10 
A.DLGH=10. 


PKTDFS 


eABORTER IS NONPRIVILEGED (1=YES) 
*ABORT FROM DIRECTIVE (0=YES) 

ABORT FROM CLI COMMAND (1=YES) 

SIZE OF PARITY ERROR AST CONTROL BLOCK 
sUCB OF TERM ISSUING DEBUG COMMAND 
*>LENGTH OF DEBUG (AK.TBT) AST BLOCK 


* KERNEL AST CONTROL CODES (A.CBL) 


AK .BUF=200 


AK .OCB=201 
AK.GBI=202 
AK. TBT=203 
AK.DIO=204 
AK.GGF=205 


be nie i 8 
T.wTOSB: 


I.AST: 
Tee RM: 


I.ATTL=. 


I .AADA: 
I.LGTH=. 


eASECT 


e BLKW 
eBLKB 
e BLKB 
e BLKW 
e BLKW 
- BLKW 
e BLKW 
- BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
- BLKW 


- BLKW 


I .ATRL=6*8. 


-- 


=e BV WH 


*BUFFERED I/O COMPLETION 

THIS CODE MUST BE 200 UNTIL ALL 
*>REFERENCES IN TTDRV ARE FIXED 
OFFSPRING TASK EXIT 

>SEGMENTED BUFFERED I/O COMPLETION 
°TASK FORCE T-BIT TRAP (DEBUG CMD) 
*DELAYED I/O COMPLETION 

>GRP. GBL. RUNDWN 


; I/O PACKET OFFSET DEFINITIONS 


-I/O QUEUE THREAD WORD 

*>REQUEST PRIORITY 

eEVENT FLAG NUMBER 

-TCB ADDRESS OF REQUESTOR 

ePOINTER TO SECOND LUN WORD 

*POINTER TO UNIT CONTROL BLOCK 

*1/O FUNCTION CODE | 

eVIRTUAL ADDRESS OF I/O STATUS BLOCK 
>I1/O STATUS BLOCK RELOCATON BIAS 

-I1/O STATUS BLOCK ADDRESS 

AST SERVICE ROUTINE ADDRESS 

*>RESERVED FOR MAPPING PARAMETER #1 
*PARAMETERS 1 TO 6 

USER MODE DIAGNOSTIC PARAMETER WORD 
*>MINIMUM LENGTH OF I/O PACKET (USED BY 
*-FILE SYSTEM TO CALCULATE MAXIMUM 
NUMBER OF ATTRIBUTES) 

2 *>STORAGE FOR ATT DESCR PTRS WITH I/O 
LENGTH OF I/O REQUEST CONTROL BLOCK 
*-LENGTH OF FILE SYSTEM ATTRIBUTE BLOCK 


ee ee ee 


ANCILLARY CONTROL BLOCK (ACB) DEFINITIONS 
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000000 
000002 
000004 
000006 
000007 
000010 
000012 
000013 
000014 


000010 
000012 
000014 
000016 


000020 
000022 
000024 
000030 
000034 


000000 


000002 
000004 
000006 
000010 
000012 
000014 
000016 
000020 
000022 


50 
A.REL: .BLKW 
A.DIS: .BLKW 
A.MAS: .BLKW 
A.NUM: .BLKB 
-BLKB 
A.LIN: .BLKW 
A.ACC: .BLKB 
A.STA: .BLKB 
Az LEN =* 
Se Oe 
A.IMAP: .BLKW 
A.IBUF: .BLKW 
A.ILEN: .BLKW 
A.SMAP: .BLKW 
A.SBUF: .BLKW 
A.SLEN: .BLKW 
A.IOS: .BLKW 
A.RES: .BLKW 
A.LEN2=. 
UA. ACC=1 
UA.PRO=2 
UA.ECH=4 
UA.TYP=10 
UA.SPE=20 
UA.PUT=40 
UA.CAL=100 
UA.COM=200 
UA.ALL=400 


UA.TRA=1000 


@ =e *e & 


=(0 

AeACCE? 
A.DEQU: 
A.POWE?: 
A.INPU: 
A-.OUTP: 
A.CONN: 
AeDISC: 
A-RECE: 
AePROC: 
A.CALL: 


e BLKW 
e BLKW 
e BLKW 
- BLKW 
e BLKW 
» BLKW 
e BLKW 
e BLKW 
e BLKW 
- BLKW 


el 


bp 


NON ee 


DEFINE THE ACD ENTRY 


fred ped fed fed ped at fet ped pd fe 


PKTDFS 


7;ACD RELOCATION BIAS 

;ACD DISPATCH TABLE POINTER 
;ACD FUNCTION MASK 

;ACD IDENTIFICATION NUMBER 
7; RESERVED 

7;ACD LINK WORD 

7;ACD ACCESS COUNT 

;ACD STATUS BYTE 

;LENGTH OF PROTOTYPE ACB 


*FULL ACB OVERLAPS PROTOTYPE ACB 
*ACD INTERRUPT BUFFER RELOCATION BIAS 
sACD INTERRUPT BUFFER ADDRESS 

*ACD INTERRUPT BUFFER LENGTH 

*ACD SYSTEM STATE BUFFER RELOCATION 
* BIAS 

>ACD SYSTEM STATE BUFFER ADDRESS 
*ACD SYSTEM STATE BUFFER LENGTH 
ACD I/O STATUS 

*RESERVED FOR USE BY THE ACD 

> LENGTH OF FULL ACB 


DEFINE THE FLAG VALUES IN THE OFFSET 
U.AFLG 


=F @~SG BW WE 


;ACCEPT THIS CHARACTER 

;PROCESS THIS CHARACTER 

;ECHO THIS CHARACTER 

;FORCE THIS CHARACTER INTO TYPEAHEAD 
;THIS CHARACTER HAS A SPECIAL ECHO 

;PUT THIS CHARACTER IN THE INPUT BUFFER 
;CALL THE ACD BACK AFTER THE TRANSFER: 
;COMPLETE THE INPUT REQUEST 


;ALLOW PROCESSING OF THIS I/O REQUEST 
>; TRANSFER CHARS. WHEN I/O COMPLETES 


POINTS (OFFSETS INTO THE DISPATCH TABLE) 


I/O REQUEST ACCEPTANCE ENTRY POINT 
7>I/O REQUEST DEQUEUE ENTRY POINT 

;POWER FAILURE ENTRY POINT 

; INPUT COMPLETION ENTRY POINT 

;OUTPUT COMPLETION ENTRY POINT 
;CONNECTION ENTRY POINT 

; DISCONNECTION ENTRY POINT 

; INPUT CHARACTER RECEPTION ENTRY POINT 
; INPUT CHARACTER PROCESSING ENTRY POINT 
;CALL ACD BACK AFTER TRANSFER ENTRY 
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000001 
000002 


000000 
000002 
000004 
000006 


000010 
000012 
000012 


000014 
000015 


000016 


000000 
000002 
000004 
000006 
000010 
000012 
000014 


000034 


PKTDFS 


; POINT 


DEFINE THE STATUS BITS IN A.STA OF THE PROTOTYPE ACB 


e@ @=G ®O 


AS .DEL=1 


7;ACD IS MARKED FOR DELETE 
AS .DIS=2 7;ACD IS DISABLED 
-/- 


; SECONDARY POOL COMMAND BUFFER BLOCKS 


CeCLKs: e BLKW uf *LINK WORD 

C.CTCB: .~BLKW 1 *TCB ADDRESS OF TASK TO RECEIVE COMMAND 

C.CUCB: .BLKW t >UCB ADDRESS OF RESPONSIBLE TERMINAL 

Cele rs e BLKW 1 *CHARACTER COUNT, EXCLUDING TRAILING 
°;CR 

C.CSTS: .~.BLKW i *STATUS MASK 

C.CMCD: *SYSTEM MESSAGE CODE 

C«CSO2 e BLKW 1 *STARTING OFFSET OF VALID COMMAND 
*TEXT 

CsCrRs e BLKB 1 > TERMINATOR CHARACTER 

C.CBLK: .BLKB i °*SIZE OF PACKET IN SEC POOL (32 WD.) 
* BLOCKS 

CeCTAtT: *COMMAND TEXT, FOLLOWED BY CR 

“- 


BIT DEFINITIONS FOR THE GINS (AKA WIMPS) INFORMATION 
DIRECTIVE. 


™e@ 2 BWH WO 


SF.PRV=100000 
SF.IN= 40000 


*>FUNCTION IS PRIVILEGED 
7>FUNCTION IS AN INPUT FUNCTION 


-- 


OFFSPRING CONTROL BLOCK DEFINITIONS 


SOME POSITIONAL DEPENDENCIES ARE DEPENDED ON BETWEEN THE 
OCB AND THE AST BLOCK IN THE ROUTINE $FINXT IN THE MODULE 
SYSXT. 


@ %e SE RWS WE WH VWSH WE 


=0 
O.LNK: e BLKW 1 ;OCB LINK WORD 
O.-MCRL: .BLKW 1 *>ADDRESS OF MCR COMMAND LINE 
O.PTCB: .BLKW 1 ;PARENT TCB ADDRESS 
O.AST: » BLKW 1 ;EXIT AST ADDRESS 
O.EFN: e BLKW 1 ;EXIT EVENT FLAG 
O.ESB: e BLKW iB *EXIT STATUS BLOCK VIRTUAL ADDRESS 
O.STAT: .~BLKW 8. *EXIT STATUS BUFFER 
O.LGTH=. ; LENGTH OF OCB 
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PKTDFS 


LAFF EEEEEEEEEFEEFEFEEE EEE EEEREFE EEE EFEEEREEEEEEEFEEEEEEEEEEEEEE FE FEEEEE ES 


THE FOLLOWING CPB,C.PSTS,AND C.CMCD ARE NOT CURRENTLY USED BY P/OS. 
THEY ARE, HOWEVER, RESERVED FOR A POSSIBLE FUTURE USE. 


=F BD WS 


; CLI PARSER BLOCK (CPB) DEFINITIONS 


;ADDRESS OF CLI'S TCB 
;CLI NAME 
;STATUS MASK 


000000 C.PTCB: .~BLKW 
000002 C.PNAM: .BLKW 
000006 C.PSTS: .~BLKW 
000010 C.PDPL: .BLKB ;LENGTH OF DEFAULT PROMPT 
000011 C.PCPL: .~BLKB >LENGTH O CNTRL/C PROMPT 
000012 C.PRMT: ;START OF PROMPT STRINGS. DEFAULT 

*IS CONCATENATED WITH CONTROL C PROMPT 


ee oe 


STATUS BIT DEFINITIONS 


e@ ~e@ =O 


CP.NUL=1 *PASS EMPTY COMMANDS TO CLI 

CP.MSG=2 CLI DESIRES SYSTEM MESSAGES 

CP.LGO=4 *CLI WANTS COMMANDS FROM LOGGED OFF 
Tt Yo 

CP .DSB=10 CLI IS DISABLED 

CP.PRV=20 USER MUST BE PRIV TO SET TTY TO THIS 
CL. 

CP.SGL=40 *>DON'T HANDLE CONTINUATIONS (M-PLUS 
e ONLY) 

CP.NIO=100 >MCR...-, HEL, BYE DO NO I/O TO TTY 
*HEL, BYE DO NOT SET CLI ETC. 

CP.RST=200 sABILITY TO SET TO THIS CLI IS 
eRESTRICTED 
°TO THE CLI ITSELF 

CP .EXT=400 | *>PASS TASK EXIT PROMPT REQUESTS TO CLI 

CP.POL=1000 CLI TCB IS IN SECONDARY POOL 

CP.CTC=2000 °~C NOTIFICATION PACKETS ARE WANTED 


STATUS BITS FOR COMMAND BLOCKS 


e@ @=@ ~®eE 


CC .MCR=1 *>FORCE COMMAND TO MCR 

CC.PRM=2 > ISSUE DEFAULT PROMPT 

CC .EXT=4 *>TASK EXIT PROMPT REQUEST 

CC.KIL=10 *DELETE ALL CONTINUATION PIECES FROM 
p1HisS. Try 

CC.CLI=20 >COMMAND TO BE RETREIVED BY GCCI$ ONLY 

CC .MSG=40 ;PACKET CONTAINS SYSTEM MESSAGE TO CLI 

CC.TTD=100 ;COMMAND CAME FROM TTDRV 

CC.CTC=200 ;~C NOTIFICATION PACKET 
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PKTDFS 


IDENTIFIER CODES FOR SYSTEM TO CLI MESSAGES 


CODES 0-127. ARE RESERVED FOR USE BY DIGITAL 
CODES 128.-255. ARE RESERVED FOR USE BY CUSTOMERS 


e 
g 
e 
a 
e 
a 
) 
e 
® 
8 
@ 


CM.INE=1 ;CLI INITIALIZED ENABLED 
CM.IND=2 ;CLI INITIALIZED DISABLED 
CM.CEN=3 7;CLI ENABLED 

CM.CDS=4 ;CLI DISABLED 

CM.ELM=5 7;CLI BEING ELIMINATED 
CM.EXT=6 ;CLI MUST EXIT IMMEDIATELY 
CM.LKT=7 ;NEW TERMINAL LINKED TO CLI 
CM.RMT=8. 7; TERMINAL REMOVED FROM CLI 
CM.MSG=9. ;GENERAL MESSAGE TO CLI 

= 


GROUP GLOBAL EVENT FLAG BLOCK OFFSETS 
(CURRENTLY NOT USED BY P/OS) 


e® ™6@ =e BE WS 


000000 Ge LNK: e BLKW 1 *LINK WORD 
000002 G.GRP: - BLKB 1 *GROUP NUMBER 
000003 GeSTAT: .BLKB 1] *STATUS BYTE 
000004 G.CNT: e BLKW 1 °*ACCESS COUNT 
000006 G.eEFLG: .BLKW 2 eEVENT FLAGS 
000012 G.LGTH=. *LENGTH OF GROUP GLOBAL EVENT FLAG 
°* BLOCK 
GS.DEL=1 *STATUS BIT -- MARKED FOR DELETE 


-- 


EXECUTIVE POOL MONITOR CONTROL FLAGS (HISTORICAL INTEREST 
ONLY) 


&=e@ B26e BE BE 


; SPOLST IS THE SYNCHRONIZATION WORD BETWEEN THE EXEC AND POOL 


MONITOR 

PC.HIH=1 *>HIGH POOL LIMIT CROSSED (1=YES) 

PC.LOW=2 *-LOW POOL LIMIT CROSSED (1=YES) 

PC.ALF=4 *POOL ALLOCATION FAILURE (1=YES) 

PC.XIT=200 *>FORCE POOL MONITOR TASK TO EXIT (MUST 
*>BE COUPLED WITH SETTING FE.MXT IN THE 
-FEATURE MASK) 

PC.NRM=PC.HIH*400 >POOL TASK INHIBIT BIT FOR HIGH POOL 

PC.ALM=PC.LOW* 400 >POOL TASK INHIBIT BIT FOR LOW POOL 


*>SPOLFL IS THE POOL USAGE CONTROL WORD 
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PF .INS=40 
PF.LOG=100 
PF ..REQ=200 


PF .ALL=177777 


ePSECT 


PKTDFS 


;REJECT NONPRIVILEGED INS/RUN/REM 
;NONPRIVILEGED LOGINS ARE DISABLED 
;STALL REQUEST OF NONPRIV. TASKS 


7;TAKE ALL POSSIBLE ACTIONS TO SAVE POOL 
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A.14 


Bee Be fe 


ITE .BAD 
IE.IFC 
TE.DNR 
IE.VER 
IE .ONP 
IE.SPC 
IE.DNA 
IE.DAA 
ITE.DUN 
IE.EOF 
IE.EOV 
ITE.WLK 
ITE.DAO 
ITE.SRE 
IE .ABO 
IE.PRI 
IE.RSU 
IE .OVR 
IE.BYT 
TE.BLK 
ITE .MOD 
ITE.CON 
ITE.BBE 
ITE.STK 
ITE.FHE 
IE.EOT 
IE .OFL 
TE.BCC 
ITE .NFW 
IE.DIS 


LE.NDR 
ITE .TMO 
IE.CNR 
IE.MII 
IE.SPI 


FILE 


e=e@ =8 B@@e 


ITE .NOD 


Qr1osys 


DECIMAL 


PRIMITIVE 


-23 ® 


SYSTEM STANDARD CODES, 


OCTAL 


177777 
177776 
LI DSS 
177774 
LITT ITS 
177772 
vB a ae a ge | 
177770 
Lit t6 7 
177766 
177765 
177764 
177763 
177762 
177761 
177760 
LTTISa 
177756 
LecID2 
177754 
LiF lo3 
LI 77TS2 
177710 
177706 
177705 
177702 
177677 
177676 
177673 
177673 


177670 
177641 
177640 
177635 
177634 


CODES 


177751 


QIOSYS$ 


USED BY EXECUTIVE AND DRIVERS 


Bad parameters 
Invalid function code 
Device not ready 
Parity error on device 

Hardware option not present 

Illegal user buffer 

Device not attached 

Device already attached 

Device not attachable 

End of file detected 

End of volume detected 

Write attempted to locked unit 
Data overrun 

Send/receive failure 

Request terminated 

Privilege violation 

Sharable resource in use 

Illegal overlay request 

Odd byte count (or virtual address) 
Logical block number too large 
Invalid UDC module # 

UDC connect error 

Bad block on device 

Not enough stack space (FCS or FCP) 
Fatal hardware error on device 

End of tape detected 
Device off line 
Block check, CRC, or 
Path lost to partner 
Path lost to partner 


framing error 
*THIS CODE MUST BE ODD 
;DISCONNECTED (SAME 


AS NFW) 
No dynamic space available ; SEE ALSO IE.UPN 
Timeout on request > see also IS.TMO 


Connection rejected 
Media inserted incorrectly 
Spindown ignored 


Caller's nodes exhausted 
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ITE.DFU 
IE.IFU 
TE.NSF 
ITE.LCK 
ITE .HFU 
ITE .WAC 
TE.CKS 
LE .WAT 
IE.RER 
ITE .WER 
ITE .ALN 
TE.«SNC 
ITE.SQC 
ITE.NLN 
ITE.CLO 
ITE.DUP 
IE.BVR 
ITE.BHD 
TBE .EXP 
IE.BTF 
ITE.ALC 
[Tk .ULK 
ITE .WCK 
ITE.DSQ 


FILE 


=e =e B@S 


CE .NBF 
ITE.RBG 
IE .NBK 
IB.ILL 
IE.BTP 
[TE.RAC 
IE.RAT 
ITE.RCN 
ITE.2DV 
IE .FEX 
ITE.BDR 
IE.RNM 
IE.BDI 
TE.FOP 
LTE.BNM 
IE.BDV 
ITE .NFI 
IE.ISQ 
ITE .NNC 


177750 
177747 
177746 
177745 
177744 
177743 
177742 
177741 
177740 
177737 


177736 


da a ge be. 
177734 
LITI33 
177732 
LET TOF 
177701 
177700 
177665 
177664 
177654 
177653 
177652 
177646 


CONTROL SERVICES 


-77. 


LIP ESL 
177730 
by A a i 
177726 
177725 
177724 
Lisi23 
177722 
177720 
177717 
177716 
177715 
177714 
LETTS 
177712 
177711 
177704 
177703 
177663 


; NETWORK ACP, PSI, AND 


Orosys 


Device full 

Index file full 

No such file 

Locked from read/write access 
File header full 

Accessed for write 

File header checksum failure 
Attribute control list format error 
File processor device read error 
File processor device write error 
File already accessed on LUN 

File ID, file number check 

File ID, sequence number check 

No file accessed on LUN 

File was not properly closed 
ENTER - duplicate entry in directory 
Bad version number 

Bad file header 

File expiration date not reached 
Bad tape format 

Allocation failure 

Unlock error 

Write check failure 

Disk quota exceeded 


CODES 


OPEN - no buffer space available for file 
Illegal record size 

File exceeds space allocated, no blocks 
Illegal operation on file descriptor block 
Bad record type 

Illegal record access bits set 

Illegal record attributes bits set 


Illegal record number - too large 
Rename - 2 different devices 
Rename - new file name already in use 


Bad directory file 

Can't rename old file system 
Bad directory syntax 

File already open 

Bad file name 

Bad device name 

File ID was not specified 
ITllegal sequential operation 
Not ANSI ‘'D’ format byte count 


DECDATAWAY CODES 
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IE.NNN -68. 177674 
ITE.BLB -70. LTE OL2 
ITE .URJ oer 177667 
ITE.NRJ -74. 177666 
ITE.NDA sa ao" 177662 
ITE.IQU -9l. 177645 
ITE.RES =O2 177644 
IE.TML =o 3 177643 
LTE.NNT -94. 177642 
IE.UKN =O) 177637 


ICS/ICR ERROR CODES 


6 *@e@ ~@ 


ITE .NLK -79. 177661 


ITE .NST -80. 177660 
IE.FLN =o 14 177657 


TITY ERROR CODES 


Se BES  @ 


IE.PES -83. Lt 7655 


RECONFIGURATION CODES 


e=e@ ™@6 = 6 


IE.ICE -47. Li ted 
TE.ONL = 6 Js L7 1675 


PCL ERROR CODES 


&e we %e 


IE.FLG =69 177647 


2g =e Oe 


IS.~PND +00. 0) 


QIosys 


No such node 

Bad logical buffer 

Connection rejected by user 
Connection rejected by network 
No data available 

Inconsistent qualifier usage 
Circuit reset during operation 
Too many links to task 

Not a network task 

Unknown name 


Task not linked to specified ICS/ICR interrupts 
Specified task not installed 


Device offline when offline request was issued 


Invalid escape sequence 
Partial escape sequence 


Internal consistancy error 
Device online 
Unable to size device 


Task not triggered 
Transfer rejected by receiving CPU 
Event flag already specified 


SUCCESSFUL RETURN CODES---~- 


OPERATION PENDING 
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OIOoSsYSs 


IS.SUC +01. 1 OPERATION COMPLETE, SUCCESS 

IS.RDD FOZ. Z FLOPPY DISK SUCCESSFUL COMPLETION 
OF A READ PHYSICAL, AND DELETED 
DATA MARK WAS SEEN IN SECTOR HEADER 


IS .TNC +02. Z (PCL) SUCCESSFUL TRANSFER BUT MESSAGE 
TRUNCATED (RECEIVE BUFFER TOO SMALL). 
IS .CHW +04. fh (IBM COMM) DATA READ WAS RESULT OF 
IBM HOST CHAINED WRITE OPERATION 
IS.BV FO Dis a (A/D READ) AT LEAST ONE BAD VALUE 


WAS READ (REMAINDER MAY BE GOOD). 

BAD CHANNEL IS INDICATED BY A 

NEGATIVE VALUE IN THE BUFFER. 
IS.DAO +02. 2 SUCCESSFUL BUT WITH DATA OVERRUN 

(NOT TO BE CONFUSED WITH IE.DAO) 


TTY SUCCESS CODES 


Se BW WE 


IS.CR_ <015*400+1> CARRIAGE RETURN WAS TERMINATOR 
IS.ESC <33*400+1> ESCAPE (ALTMODE) WAS TERMINATOR 
IS.CC <3*400+1> CONTROL-C WAS TERMINATOR 

IS .ESQ <0233*400+1> ESCAPE SEQUENCE WAS TERMINATOR 

IS.PES <200*400+1> PARTIAL ESCAPE SEQUENCE TERMINATOR 
IS .EOT <4*400+1> EOT WAS TERMINATOR (BLOCK MODE INPUT) 
IS.TAB <11*400+1> TAB WAS TERMINATOR (FORMS MODE INPUT) 
IS .TMO +2. 2 REQUEST TIMED OUT 


Professional Bisync Success Codes 


oe =e 26 


IS.RVI +2. 2 DATA SUCC. XMITTED; HOST ACKED W/RVI 
IS .CNV +36 5 DATA SUCC. XMITTED; HOST ACKED W/CONVERSATION 
IS.XPT +2 5 DATA SUCC. RECVD IN TRANSPARENT MODE 


Professional Bisync Abort Codes 


These codes are returned in the high byte of the first word of the IOSB 
when the low byte contains IE.ABO. 


@=e@ BSE BE WE WE WS 


5B.KIL Ss oe a ABORTED BY IO.KIL 

SB.ACK = 2's 376 ABORTED BECAUSE TOO MANY ACKS RECD OUT OF SEQ 
5B.NAK =3\% 3 es: ABORTED BECAUSE NAK THRESHOLD EXCEEDED 

SB.ENO -4. 374 ABORTED BECAUSE ENQ THRESHOLD EXCEEDED 

SB.BOF = Ds 373 ABORTED BECAUSE OF IO0O.RLB BUFFER OVERFLOW 
SB.TMO -6. a ABORTED BECAUSE OF TIMEOUT 

oB.DIS ice 37] ABORTED BECAUSE HOST DISCONNECTED W/ DLE, EOT 


® 
g 
@ 
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STANDARD ERROR CODES RETURNED BY DIRECTIVES IN THE DIRECTIVE 


A-50 


orosys 


; STATUS WORD 
IE.UPN -Ol. 177777 Insufficient dynamic storage ; SEE ALSO 
IE-NDR 

IE.INS -02. 177776 Specified task not installed 

IE.PTS ~03. 177775 Partition too small for task 

IE.UNS -04. 177774 Insufficient dynamic storage for send 

IE.ULN -05. 177773 Un-assigned LUN 

IE.HWR -06. 177772 Device handler not resident 

IE.ACT -O7. 177771 Task not active 

IE.ITS ~0O8. 177770 Directive inconsistent with task state 

IE.FIX -09. 177767 Task already fixed/unfixed 

IE.CKP ~10. 177766 Issuing task not checkpointable 

IE.TCH =~ll. 177765 Task is checkpointable 

IE.RBS ~15. 177761 Receive buffer is too small 

IE.PRI ~16. 177760 Privilege violation 

IE.RSU -~l7. 177757 Resource in use 

IE.NSW ~18. 177756 No swap space available 

IE.ILV =19'5 177755 Illegal vector specified 

ITE.ITN -~20. 177754 Invalid table number 

IE.LNF -~21l. 177753 Logical name not found 

IE.AST -80. 177660 Directive issued/not issued from AST 

ITE .MAP -8l. 177657 Illegal mapping specified 

IE.IOP ~83. 177655 Window has I/O in progress 

ITE .ALG -84., 177654 Alignment error 

IE.WOV -85. 177653 Address window allocation overflow 

IE.-NVR -86. 177652 Invalid region ID 

ITE .NVW -~87. 177651 Invalid address window ID 

IE.ITP -88. 177650 Invalid TI parameter | 
IE.IBS -89. 177647 Invalid send buffer size ( .GT. 255.) 
- IE.LNL -90. 177646 LUN locked in use 

IE.IUI -~9l. 177645 Invalid UIC 

IE.IDU ~92. 177644 Invalid device or unit 

TEslTti -~93. 177643 Invalid time parameters 

IE.-PNS -94. 177642 Partition/region not in system 

IE.IPR = 9 5% 177641 Invalid priority ( 250.) 

LE «LLU ~“96. 177640 Invalid LUN 

IE.IEF -97. 177637 Invalid event flag ( .GT. 64.) 

TE .ADP =98. 177636 Part of DPB out of user's space 

IE.SDP -99. 177635 DIC or DPB size invalid 


* SUCCESS CODES FROM DIRECTIVES - PLACED IN THE DIRECTIVE STATUS WORD 


IS.CLR 0 0 EVENT FLAG WAS CLEAR 

FROM CLEAR EVENT FLAG DIRECTIVE 
IS .SET 2 2 EVENT FLAG WAS SET 

FROM SET EVENT FLAG DIRECTIVE 
IS.SPD 2 Z TASK WAS SUSPENDED 
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IS.SUP 


Se =@ BG BS % @ 
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IQ.Q 
IQ.S 
ITQ.UMD 
IQ.LCK 


=e =6& =O 


IO.KIL 
LO.RDN 
IO.UNL 
IO.LTK 
IO.RTK 
I0O.SET 
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IO.WLB 
IO.RLB 
ITO. LOV 
ITO.LDO 
IO.ATT 
IO.DET 


> 


SUGGESTIVE PURPOSES. 
ARE SUPPORTED ON P/OS. 


000001 
000002 
000004 
000004 
000200 


000012 
000022 
000042 
000050 
000060 
000030 


GENERAL DEVICE 


000400 
001000 
001010 
001110 
001400 
002000 


QIrIosys 


3 LOGICAL NAME SUPERSEDED 


COLUMN HEADINGS: 


WORD CODE SUBCODE 
EQUIVALENT (HIGH (LOW 
BYTE) BYTE) 


EXPRESS QUEUE COMMANDS 


000 001 
000 002 
000 004 
000 004 
000 200 
000 012 
000 022 
000 042 
000 050 
000 060 
000 030 


HANDLER CODES 


001 000 
002 000 
002 010 
002 110 
003 000 
004 000 


* DIRECTORY PRIMITIVE CODES 


IO.RNA 
IO.ENA 


@ 
G 
e 
g 
e 
a 

ui 


O.CLN 


004400 
005400 
006000 


FILE PRIMITIVE 


003400 


O11 000 
OLS 000 
O14 000 
CODES 

007 000 


THE FOLLOWING LIST IS PROVIDED FOR COMPLETENESS AND INFORMATIVE OR 
NOT ALL OF THE I/O FUNCTION CODES AND DEVICES 


GENERAL I/O QUALIFIER BYTE DEFINITIONS 


NO ERROR RECOVERY 

QUEUE REQUEST IN EXPRESS QUEUE 
SYNONYM FOR IQ.UMD 

USER MODE DIAGNOSTIC STATUS REQUIRED 
MODIFY IMPLIED LOCK FUNCTION 


KILL CURRENT REQUEST 

I/O RUNDOWN 

UNLOAD I/O HANDLER TASK 

LOAD A TASK IMAGE FILE 
RECORD A TASK IMAGE FILE 

SET CHARACTERISTICS FUNCTION 


WRITE LOGICAL BLOCK 
READ LOGICAL BLOCK 

LOAD OVERLAY (DISK DRIVER) 
LOAD D-SPACE OVERLAY (DISK) 
ATTACH A DEVICE TO A TASK 
DETACH A DEVICE FROM A TASK 


FIND FILE NAME IN DIRECTORY 
REMOVE FILE NAME FROM DIRECTORY 
ENTER FILE NAME IN DIRECTORY 


CLOSE OUT LUN 
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ITO.ULK 
IO.ACR 
IO.ACW 
IO.ACE 
IO.DAC 
IO.RVB 
IO.WVB 
IO.EXT 
TO.CRE 
IO.DEL 
IQ.RAT 
IO.WAT 
IO.APV 
ITO.APC 


e@ =@ BE 


IO.WLV 
ITO.WLS 
IO.WNS 
IO.WAL 
IO.WMS 
IO.CCO 
ITO.WBT 
IO.WLT 
IO.WLC 
ITO.WPB 
IO.WDD 


IO.RSN 
IO.RLV 
IO.RST 
IO.RAL 
IO.RNE 
LO.RNC 
ITO.RTM 
LO.RDB 
IO.SCF 
IO.RHD 
IO.RNS 
IO.CRC 
ITO.RPB 
IO.RLC 


IO.ATA 
IQO.GTS 


IO.RIC 
IO.INL 
IO.TRM 
ITO.RWD 


005000 
006400 
007000 
007400 
010000 
010400 
011000 
011400 
012000 
012400 
013000 
013400 
014010 
014000 


000500 
000410 
000420 
000410 
000420 
000440 
000500 
000410 
000420 
000440 
000540 


001140 
001100 
001001 
001010 
001020 
001040 
001200 
001200 
001200 
001010 
001020 
001040 
001040 
001020 


001410 
002400 


002400 
002400 
002410 
002400 


012 
015 
016 
017 
020 
O21 
022 
023 
024 
025 
026 
027 
030 
030 


I/O FUNCTION CODES 


FOR 


000 
000 
000 
000 
000 
000 
000 


000. 


000 
000 


000. 


000 
010 
000 


OIOSsyYSs 


UNLOCK 
ACCESS 


BLOCK 

FOR READ 
ACCESS FOR WRITE 
ACCESS FOR EXTEND 
DE-~ACCESS FILE 

READ VIRITUAL BLOCK 
WRITE VIRITUAL BLOCK 
EXTEND FILE 

CREATE FILE 

DELETE FILE 

READ FILE ATTRIBUTES 
WRITE FILE ATTRIBUTES 
PRIVILEGED ACP CONTROL 
ACP CONTROL 


SPECIFIC DEVICE DEPENDENT FUNCTIONS 


100 
010 
020 
010 
020 
040 
100 
010 
020 


(DECTAPE) WRITE LOGICAL REVERSE 
(COMM.) WRITE PRECEDED BY SYNC TRAIN 
(COMM.) WRITE, NO SYNC TRAIN 
(TTY) WRITE PASSING ALL CHARACTERS 
(TTY) WRITE SUPPRESSIBLE MESSAGE 
(TTY) WRITE WITH CANCEL CONTROL-O 
(TTY) WRITE WITH BREAKTHROUGH 
(DISK) WRITE LAST TRACK 
(DISK) WRITE LOGICAL W/ WRITECHECK 
(DISK) WRITE PHYSICAL BLOCK 
(FLOPPY DISK) WRITE PHYSICAL W/ 
DELETED DATA 
(MSCP DISK) READ VOLUME SERIAL NUMBER 
(MAGTAPE,DECTAPE) READ REVERSE 
(TTY) READ WITH SPECIAL TERMINATOR 
(TTY) READ PASSING ALL CHARACTERS 
(TTY) READ WITHOUT ECHO 
(TTY) READ - NO LOWER CASE CONVERT 
(TTY) READ WITH TIME OUT 
(CARD READER) READ BINARY MODE 
(DISK) SHADOW COPY FUNCTION 
(COMM.) READ, STRIP SYNC 
(COMM.) READ, DON'T STRIP SYNC 
(COMM.) READ, DON'T CLEAR CRC 
(DISK) READ PHYSICAL BLOCK 
(DISK,MAGTAPE) READ LOGICAL 
W/ READCHEC;**¥-]1 
(TTY) ATTACH WITH AST'S 
(TTY) GET TERMINAL SUPPORT 
CHARACTERISTICS 
(AFC,AD01,UDC) READ SINGLE CHANNEL 
(COMM.) INITIALIZATION FUNCTION 
(COMM.) TERMINATION FUNCTION 
(MAGTAPE,DECTAPE) REWIND 
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IO.SPB 
ITO.RPL 


IO.SPF 
IO.STC 
IO.SMD 
IO.SEC 
LO.RWU 
LO.SMO 
IO.HNG 
LO.HLD 
TO.BRK 
TO.RBC 


IO.MOD 
TO.HDX 
IO.FDX 
IO.SYN 
IO.EOF 
IO.ERS 
IO.DSE 
IO.RDF 
IO.RTC 
IO.SAO 
IO.SSO 
IO.RPR 
IO0.MSO 
IO.RTT 
-I0.SLO 
IO.MLO 
IO.LED 
IO.SDO 
IO.SDI 
TO.SCS 
IO.REL 
IO.MCS 
IO.ADS 
LOSCCI 
TO< LOD 
IO.MDI 
IO.DCI 
IO.PAD 
HT.RPP 
IO.XMT 


IO.XNA 
IO.INI 
IO.HIS 
LO.RCI 
LO.RCV 


002420 
002420 


002440 
002500 
002510 
002520 
002540 
002560 
003000 
003100 
003200 
003000 


003000 
003010 
003020 
003040 
003000 
003020 
003040 
003110 
003400 
004000 
004400 
004400 
005000 
005001 
005400 
006000 
012000 
012400 
013000 
013000 
013400 
013400 
014000 
014000 
014000 
014400 
014400 
014400 
000010 
014400 


014410 
014400 
015000 
015000 
015000 


OIosyYs 


(MAGTAPE) SPACE "N" BLOCKS 

(DISK) REPLACE LOGICAL BLOCK 
(RESECTOR) 

(MAGTAPE) SPACE "N" EOF MARKS 

SET CHARACTERISTIC 

(FLOPPY DISK) SET MEDIA DENSITY 

SENSE CHARACTERISTIC 

(MAGTAPE,DECTAPE) REWIND AND UNLOAD 

(MAGTAPE) MOUNT & SET CHARACTERISTICS 

(TTY) HANGUP DIAL-UP LINE 

(TMS) HANGUP BUT LEAVE LINE ON HOLD 

(PRO/TTY) SEND SHORT OR LONG BREAK 

READ MULTICHANNELS (BUFFER DEFINES 
CHANNELS) 

(COMM.) SETMODE FUNCTION FAMILY 

(COMM.) SET UNIT HALF DUPLEX 

(COMM.) SET UNIT FULL DUPLEX 

(COMM.) SPECIFY SYNC CHARACTER 

(MAGTAPE) WRITE EOF 

(MAGTAPE) ERASE TAPE 

(MAGTAPE) DATA SECURITY ERASE 

(DISK) READ DISKETTE FORMAT 

READ CHANNEL - TIME BASED 

(UDC) SINGLE CHANNEL ANALOG OUTPUT 

(UDC) SINGLE SHOT, SINGLE POINT 

(TTY) READ WITH PROMPT 

(UDC) SINGLE SHOT, MULTI-POINT 

(TTY) READ WITH TERMINATOR TABLE 

(UDC) LATCHING, SINGLE POINT 

(UDC) LATCHING, MULTI-POINT 

(LPS11) WRITE LED DISPLAY LIGHTS 

(LPS11) WRITE DIGITAL OUTPUT REGISTER 

(LPS11) READ DIGITAL INPUT REGISTER 

(UDC) CONTACT SENSE, SINGLE POINT 

(LPS11) WRITE RELAY 

(UDC) CONTACT SENSE, MULTI-POINT 

(LPS11) SYNCHRONOUS A/D SAMPLING 

(UDC) CONTACT INT -— CONNECT 

(LPA11) LOAD MICROCODE 

(LPS11) SYNCHRONOUS DIGITAL INPUT 

(UDC) CONTACT INT -— DISCONNECT 

(PSI) DIRECT CONTROL OF X.29 PAD 

(PSI) RESET PAD PARAMETERS SUBFUNCTION 

(COMM.) TRANSMIT SPECIFIED BLOCK WITH 
ACK 

(COMM.) TRANSMIT WITHOUT ACK 

(LPA11) INITIALIZE 

(LPS11) SYNCHRONOUS HISTOGRAM SAMPLING 

(UDC) CONTACT INT - READ 

(COMM.) RECEIVE DATA IN BUFFER 
SPECIFIED 


ITO.CLK 
IO.CSR 
LO.MDO 
IO.CTI 
IO.CON 


IO .-ORG 


IO.ANS 
IO.STA 


IO.DTI 
IO.DIS 


IO.MDA 
IO.DPT 


IO.RTI 


IO.CTL 
IO.STP 


IO.SWI 
IO.CNT 


IO.ITI 
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IO.RSD 
ITO.WSD 


015000 
015000 
015400 
015400 
015400 


015410 


015420 
015400 


016000 
016000 


016000 
016010 


016400 


016400 
016400 


016400 
017000 


017000 


PRO 300 SERIES 


NOTE: 


032 
032 
033 
033 
033 


033 


033 
033 


034 
034 


034 
034 


035 


035 
035 


035 
036 


036 


000 
000 
000 
000 
000 


010 


020 
000 


000 
000 


000 
010 


000 


000 
000 


000 
000 


000 


QIosys 


(LPA11) START CLOCK 

(BUS SWITCH) READ CSR REGISTER 

(LPS11) SYNCHRONOUS DIGITAL OUTPUT 

(UDC) TIMER -— CONNECT 

(COMM.) CONNECT FUNCTION 

(VT11) -—- CONNECT TASK TO DISPLAY 
PROCESSOR 

(BUS SWITCH) CONNECT TO SPECIFIED BUS 

(COMM./PRO) DIAL TELEPHONE AND ORIGINATE 

(COMM.) INITIATE CONNECTION IN 
ORIGINATE MODE 


(COMM.) INITIATE CONNECTION IN ANSWER MODE 


(LPA11) START DATA TRANSFER 

(XJDRV) - SHOW STATE 

(UDC) TIMER - DISCONNECT 

(COMM.) DISCONNECT FUNCTION 

(VT11) - DISCONNECT TASK FROM DISPLAY 
PROCESSOR 

(BUS SWITCH) SWITCHED BUS DISCONNECT 

(LPS11) SYNCHRONOUS D/A OUTPUT 

(BUS SWITCH) DISCONNECT TO SPECIF 
PORT NO. 

(UDC) TIMER — READ 

(COMM.) NETWORK CONTROL FUNCTION 

(LPS11,LPA11) STOP IN PROGRESS 
FUNCTION 

(VT11) - STOP DISPLAY PROCESSOR 

(BUS SWITCH) SWITCH BUSSES 

(VT11) -— CONTINUE DISPLAY PROCESSOR 

(XJDRV) —- SHOW COUNTERS 

(UDC) TIMER - INITIALIZE 


BITMAP FUNCTIONS 


TO CHANGE 


006030 
005410 


014 
013 


SD.TXT 
SD.GDS 


030 
010 


THESE FUNCTIONS ARE FOR DEC USE ONLY AND ARE SUBJECT 


READ SPECIAL DATA 
WRITE SPECIAL DATA 


TEXT DATA TYPE FOR SPECIAL DATA 
GIDIS DATA TYPE FOR SPECIAL DATA 


> PROFESSIONAL 300 BISYNC DRIVER (XJDRV) FUNCTIONS 


SB.PRT 
SB.CLR 


SB.RDY 
SB.NRD 


001420 
017010 


015410 
015420 


003 
036 


033 
033 


020 
010 


010 
020 


ATTACH AS A PRINTER 

CLEAR COUNTERS (IO.CNT 

SUBFUNCTION) 

SET DEVICE STATE READY (IO.STA SUBFUNC) 
SET DEVICE STATE NOT READY 
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ITO.LBK 016400 
SB.CBL 016410 
5SB.CLK 016420 
; COMMUNICATIONS 
ITO.CPR 015410 
LTO.CAS 015420 
ITO.CRJ 015440 
ITO.CBO 015510 
IO.CTR 015610 
IO.GNI 016410 
IO.GLI 016420 
TO.GLC 016430 
IO.GRI 016440 
ITO.GRC 016450 
ITO.GRN 016460 
IO.CSM 016470 
IO.CIN 016500 
IO.SPW 016510 
TO.CPW 016520 
ITO.NLB 016530 
IO.DLB 016540 
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IO.CTY 
IO.DTY 
IO.LDI 
IO.UDI 
IO.LTI 
IO.UTI 
LOSE TY 
IO.UTY 
IO.LKE 
IO.UER 
IO.NLK 
IO.ONL 
IO.FLN 
ITO.RAD 


°« IPIl 
TO.MAO 


IO.LEL 
ITO.RDD 


003400 
006400 
007000 
011410 
007400 
011420 
010000 
011430 
012000 
011440 
011400 
017400 
012400 
010400 


003410 
007410 
010010 


ICS/ICR I/O FUNCTIONS 


I/O FUNCTIONS 


035 000 
035 010 
035 020 
FUNCTIONS 

033 010 
033 020 
033 040 
033 110 
033 210 
035 010 
035 020 
035 030 
035 040 
035 050 
035 060 
035 070 
0:35 100 
035 110 
035 120 
035 130 
035 140 
007 000 
015 000 
016 000 
023 010 
017 000 
023 020 
020 000 
023 030 
024 000 
023 040 
023 000 
037 000 
025 000 
O21 000 
007 010 
017 010 
020 010 


QLIOSsyYS 


PERFORM LOOPBACK TEST 


PERFORM CABLE LOOPBACK TEST 
DEVICE PERFORMS LINE CLOCKING 


CONNECT NO TIMEOUTS 

CONNECT WITH AST 

CONNECT REJECT 

BOOT CONNECT 

TRANSPARENT CONNECT 

GET NODE INFORMATION 

GET LINK INFORMATION 

GET LINK INFO CLEAR COUNTERS 
GET REMOTE NODE INFORMATION 
GET REMOTE NODE ERROR COUNTS 
GET REMOTE NODE NAME 

CHANGE SOLO MODE 

CHANGE CONNECTION INHIBIT 
SPECIFY NETWORK PASSWORD 
CHECK NETWORK PASSWORD. 

NSP LOOPBACK 

DDCMP LOOPBACK 


CONNECT TO TERMINAL INTERRUPTS 
DISCONNECT FROM TERMINAL INTERRUPTS 
LINK TO DIGITAL INTERRUPTS 

UNLINK FROM DIGITAL INTERRUPTS 

LINK TO COUNTER MODULE INTERRUPTS 
UNLINK FROM COUNTER MODULE INTERRUPTS 
LINK TO REMOTE TERMINAL INTERRUPTS 
UNLINK FROM REMOTE TERMINAL INTERRUPTS 
LINK TO ERROR INTERRUPTS 

UNLINK FROM ERROR INTERRUPTS 

UNLINK FROM ALL INTERRUPTS 

UNIT ONLINE 

UNIT OFFLINE 

READ ACTIVATING DATA 


MULTIPLE ANALOG OUTPUTS 
LINK EVENT FLAGS TO INTERRUPT 
READ DIGITAL DATA 
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IO.RMT 
IO.LSI 
IO.UETI 
IQO.USI 
IO.CSI 
IO.DSI 
ITO.RAM 
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IO.ATX 
IO.ATF 
TO.CRX 
ITO.DRX 
IO.RTF 
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IQ.UMD 
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ITO.HMS 
IO.BLS 
IO.OFF 
ITOQ.RDH 
IO.WDH 
ITO.WCK 
IO.RNF 
ITO.RNR 
ITO.RDS 
IO.LPC 


IO.RTD 
TO.WTD 
I0O.TDD 


IO.DGN 
IO.WPD 
ITO.RPD 
IO.CER 
TO.CEW 


DEFINE 


DEFINE 


010020 
011000 
011450 
011460 
013000 
013400 
015000 


000400 
001000 
014400 
015000 
015400 


PCL11 I/O FUNCTIONS 


O01 
002 
031 
032 
033 


020 
000 
050 
060 
000 
000 
000 


000 
000 
000 
000 
000 
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READ MAPPING TABLE 

LINK TO DSI INTERRUPTS 

UNLINK EVENT FLAGS 

UNLINK FROM DSI INTERRUPTS 
CONNECT TO DSI INTERRUPTS 
DISCONNECT FROM DSI INTERRUPTS 
READ ANALOG MAPPING TABLES 


ATTEMPT TRANSMISSION 
ACCEPT TRANSFER 

CONNECT FOR RECEPTION 
DISCONNECT FROM RECEPTION 
REJECT TRANSFER 


THE GENERAL USER-MODE I/O QUALIFIER BIT. 


000004 


000 


004 


USER MODE DIAGNOSTIC REQUEST 


USER-MODE DIAGNOSTIC FUNCTIONS. 


004000 
004010 
004020 
004030 
004040 
004050 
004060 
004070 
004070 
004100 


004120 
004130 
004140 


004150 
004160 
004170 
004200 
004210 


010 
010 
010 
010 
010 
010 
010 
010 
010 
010 


010 
010 
010 


010 
010 
010 
010 
010 


000 
010 
020 
030 


(DISK) HOME SEEK OR RECALIBRATE 

(DISK) BLOCK SEEK 

(DISK) OFFSET POSITION 

(DISK) READ DISK HEADER 

(DISK) WRITE DISK HEADER 

(DISK) WRITECHECK (NON-TRANSFER) 

(DECTAPE) READ BLOCK NUMBER FORWARD 

(DECTAPE) READ BLOCK NUMBER REVERSE 

(DISK-RX50) RETURN DISKETTE SPEED 

(MAGTAPE) READ LONGITUDINAL PARITY 
CHAR 

(DISK) READ TRACK DESCRIPTOR 

(DISK) WRITE TRACK DESCRIPTOR 

(DISK) WRITE TRACK DESCRIPTOR 
DISPLACED 

DIAGNOSE MICRO PROCESSOR FIRMWARE 

(DISK) WRITE PHYSICAL BLOCK 

(DISK) READ PHYSICAL BLOCK 

(DISK) READ CE BLOCK 

(DISK) WRITE CE BLOCK 
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SCBDFS,,SYSDF 


A.15 SCBDFS,,SYSDF 


+ 


STATUS CONTROL BLOCK 


THE STATUS CONTROL BLOCK (SCB) DEFINES THE STATUS OF A DEVICE 
CONTROLLER. THERE IS ONE SCB FOR EACH CONTROLLER IN A SYSTEM. 
THE SCB IS POINTED TO BY UNIT CONTROL BLOCKS. NORMALLY, AN 
SCB EXISTS FOR EACH "PROCESS" THAT A DRIVER CAN POSSIBLY HAVE 
CONCURRENTLY ACTIVE. FOR EXAMPLE, A DISK THAT SUPPORTS 


e =e =@ =e BE BQ BQ BSH WH WH WHE WH BSE BG BH] WHE WH WH WE WH WS & eo 
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OVERLAPPED SEEK OPERATIONS REQUIRES THAT THERE EXIST A 
SEPARATE SCB FOR EACH UNIT THAT CAN BE ACTIVE. 
THE FORKBLOCK IN THE SCB IS USED TO SUSPEND THE DRIVER PROCESS 
DURING GTPKT AND IS LINKED INTO THE CONTROLLER REQUEST QUEUE 
WHOSE LISTHEAD IS IN THE KRB OF THE ASSIGNED CONTROLLER 
(USUALLY STATIC S.KRB). 


IN THIS CASE, 


IN ADDITION TO CONTAINING THE DRIVER'S PROCESS CONTEXT AND 
DEFINING THE STATE OF THE CURRENT CONTROLLER STATE (NOT 
NECESSARILY THE PHYSICAL CONTROLLER STATE) A LISTHEAD IS 
MAINTAINED OF ALL PENDING I/O PACKETS TO BE PROCESSED. 


SYSDF 

-ASECT 
000000 S.LHD: .BLKW 2 *>PENDING I/O REQUEST (PACKET) QUEUE 

° LISTHEAD 
000004 S.FRK: .BLKW i °FORK BLOCK LINK WORD 
000006 - BLKW 1 > FORK-PC 
000010 - BLKW 1 *FORK-R5 
000012 - BLKW ii °FORK-R4 
000014 S.KS5: .BLKW i °FORK KISARS5 
000016 S.PKT: .BLKW i) ADDRESS OF CURRENT I/O PACKET 
000020  S.CTM: .BLKB 1 eCURRENT TIMEOUT COUNT 
000021 S.ITM: .BLKB ii e INITIAL TIMEOUT COUNT 
000022 S.STS:  .BLKB 1 STATUS (O=FREE, NE O=BUSY) 
000023 S.ST3:  .BLKB 1 STATUS EXTENSION BYTE 
000024 S.ST2: .BLKW 1 STATUS EXTENSION 
000026 S.KRB: .BLKW 1 eADDRESS OF KRB 
000030 S.RCNT: .BLKB i *NUMBER OF REGISTERS TO COPY 
| ©(NOT IN USE ) 
000031 S.ROFF: .BLKB uf OFFSET TO FIRST DEV REG TO COPY 
> (NOT IN USE) 
000032 S.EMB: .BLKW 1 *ERROR MESSAGE BLOCK POINTER 
| °(NOT IN USE) 

000034 S.KTB: ~.BLKW 1 eSTART OF MULTI-ACCESS KRBS (OPTIONAL) 

»PSECT 
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; STATUS CONTROL BLOCK STATUS EXTENSION BIT DEFINITIONS 


S2.EIP=1 *ERROR IN PROGRESS (1=YES) 
S2.ENB=2 *ERROR LOGGING ENABLED (0=YES) 
S2.LOG=4 *ERROR LOGGING SUPPORTED (1=YES) 
S2.MAD=10 | *eMULTIACCESS DEVICE (1=YES) 
S2.LDS=40 *LOAD SHARING ENABL. (1=YES, MUST BE 
°0 ON P/OS) 
S2.OPT=100 SUPPORTS EXECUTIVE BLOCK CHECKING (MAX LBN) 


SUPPORTS ACCOUNTING STATISTICS 
AND MIGHT SUPPORT SEEK OPTIMIZATION 
° (DEPENDS ON S3.OPT) 


S2.CON=200 °-SCB AND KRB ARE CONTIGUOUS (1=YES) 
S2.OP1=400 THESE TWO BITS DEFINE THE OPTIMIZATION 
S2.O0P2=1000 eMETHOD. 


7;OP2,OP1=0,0 INDICATES NEAREST CYLINDER 
7;OP2,OP1=0,1 INDICATES ELEVATOR 
7;OP2,OP1=1,0 INDICATES C-SCAN 
7;OP2,OP1=1,1 RESERVED 


— S2.ACT=2000 *DRIVER HAS OPERATION OUTSTANDING 
3 (1=YES) 
S2.XHR=4000 *>EXTERNAL HEADER AND NEW I.LN2 SUPPORT 


°-(0 FOR FILES-11 OR ANSI MAGTAPE ACPS) 


ri a 

> STATUS CONTROL BLOCK STATUS EXTENSION (S.ST3) DEFINITIONS 

S3.DRL=1 *>MULTI-ACCESS DRIVE IN RELEASED STATE 
°(1=YES) 

S3.NRL=2 *>DRIVER SHOULDN'T RLS MULTI-ACCESS 
*DRIVE (1=YES) 

S3.SIP=4 *>SEEK IN PROGRESS (1=YES) 

S3 .ATN=10 *DRIVER MUST CLEAR ATTENTION BIT 
> (1=YES) 

S3.SLV=20 °DEVICE USES SLAVE UNITS (1=YES) 

S3.SPA=40 *PORT 'A' SPINNING UP 

S3.SPB=100 >PORT SPINNING UP 

S3.OPT=200 *>SEEK OPTIMIZATIONS ENABLED (1=YES) 

S3.SPU=S3.SPA!S3.SPB ° OR. OF PORT SPINUP BITS 

ot 

> KRB ADDRESS TABLE (S.KTB) PORT OFFLINE FROM THIS SCB FLAG. 

KP.OFL=1 >KRB ADDRESS POINTS TO OFFLINE PORT (1=YES) 


rig 
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MAPPING ASSIGNMENT BLOCK (FOR UNIBUS MAPPING REGISTER 
ASSIGNMENT) ..OF HISTORICAL INTEREST ONLY ON P/OS AND 
QBUS PROCESSORS 


™=6 ™*E BW WS 


e-ASECT 

-=0 

M.LNK: e BLKW J ; LINK WORD 

M.e-UMRA: .BLKW 1 7;ADDRESS OF FIRST ASSIGNED UMR 

M.e.UMRN: .BLKW t ;NUMBER OF UMR'S ASSIGNED * 4 

M.e.UMVL: .~BLKW 1 ;LOW 16 BITS MAPPED BY 1ST ASSIGNED 
7;UMR 

M.UMVH:s .BLKB 1 ;HIGH 2 BITS MAPPED IN BITS 4 AND 5 

M.e.BFVH: .BLKB 1 ;HIGH 6 BITS OF PHYSICAL BUFFER 
7;ADDRESS 

M.e-BFVL: .~.BLKW 1 ;LOW 16 BITS OF PHYSICAL BUFFER 
7; ADDRESS 

M.LGTH= . ;LENGTH OF MAPPING ASSIGNMENT BLOCK 

e ENDC 

ePSECT 
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A.16 TTSYMS 


DECIMAL OCTAL 


TTSYMS 


TC.WID Is i} LINE WIDTH 

TCeLPP 2 2 LINES PER PAGE 

TC.RSP 3% 3 RECEIVER SPEED 

TC.XSP 4. 4 TRANSMITTER SPEED 

TC.STB 5. 5 TWO STOP BITS 

TCaloL 6. 6 SUBLINE ON INTERFACE 

TC.RAT Ts 7 READ-AHEAD TYPE 

TEeTTPR: «<8. 10 TERMINAL TYPE 

TC.SCR 9. ala SCRIPT LINE 

TC.SCP 10. 12 SCOPE 

TC .HFL Le 13 HORIZONTAL FILL REQUIREMENT 

TCeVEL 12 14 VERTICAL FILL 

TCSNL 135 15 ASCII NEWLINE TERMINAL 

TC.SFF 14. 16 SIMULATE FORMFEED AND VERTAB 

TC.HFF L5% 17 HARDWARE FORMFEED AND VERTAB 

TC.LVF 16. 20 LA36 VERTICAL FILL 

TC .HHT rays 21 HARDWARE HORIZONTAL TAB 

TC.NST 18. 22 NON-STANDARD HARDWARE TAB 

TC.BSP 19. 23 HARDWARE BACKSPACE 

TC.ACR 20% 24 AUTOMATIC CARRIAGE RETURN REQUIRED 

TC.SMR 24,4 25 SMALL CHARACTER INPUT ENABLED 

TC.SMP 226 26 SMALL CHARACTER INPUT REQUIRED 
( /LOWERCASEINPUT) 

TC.SMO 23% 27 SMALL CHARACTER OUTPUT ENABLED 

TC.CCF 24. 30 CONTROL-C FLUSHES TYPE-AHEAD AND READ 

TCZALT 25. 31 ALTERNATIVE ALTMODE RECOGNITION 

TC.IMG 26% 32 IAS - MESSAGES INHIBITED 

TC.NKB 24 33 NO KEYBOARD 

TC.NPR 28. 34 NO PRINTER 

TC.ESQ 29. 35 ESCAPE SEQUENCE RECOGNITION 

TCSLCP 30. 36 LOCAL COPY LINE 

TC.PAR 36 37 PARITY RECOGNITION/GENERATION REQUIRED 

TC.EPA 32. 40 EVEN PARITY 

TC. DLU 33. 4] DIALUP LINE 

TCaBLK 34. 42 BLOCK MODE TERMINAL 

TC.FRM 354 43 FORMS MODE TERMINAL 

TC.HLD 36. 44 TERMINAL HOLD MODE 

TG. TAP 37% 45 LOW SPEED PAPER TAPE READER 

TC.CEQ 38. 46 COMPATIBLE ESCAPE SEQUENCES 

TC.NEC 39. 47 TERMINAL IN NO-ECHO MODE 

TC.SLV 40. 50 TERMINAL IN SLAVE MODE 

TC.PRI 41. sal TERMINAL IS PRIVILEGED 

TC..UCO ao 52 USER CHARACTERISTIC 0 

TC.UCI 43. 53 USER CHARACTERISTIC 1 

TCsUC2 4A. 54 USER CHARACTERISTIC 2 

TC2UC3 a5. 55 USER CHARACTERISTIC 3 

TOLUCA 46. 56 USER CHARACTERISTIC 4 
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TC2ucs 
TC.UC6 
TC.UC/ 
TC.UC8 
TC.UC9 
IC .FDX 
TC.BIN 


TC.REM 
TC.8BC 
ECer se 
TC.TBF 
TC .CTS 
TC.ANS 
TC.CSO 
TC.CTC 
TC.ASP 
TC.ABD 
TC.TBS 
TC.TBM 
TC.NBR 
TC.ACD 
TC .ARC 
TC.TRN 
TC .XMM 
TC.FSZ 
XT.DLM 


XT .DMD | 


XT.DTT 
AT.DIT 
XAT MTP 
XT .SDE 
XT. TAK 
XT .GOV 


XAT .TSP 
AT.TTO 
TC.ANI 
TC.AVO 
TC .DEC 
TC.EDT 
IC .RGS 
TC.INT 


TC.TLC 
TC .MAX 


ft. 


@~e@ BZEe WS 
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TTSYMS 


USER CHARACTERISTIC 
USER CHARACTERISTIC 
USER CHARACTERISTIC 
USER CHARACTERISTIC 
USER CHARACTERISTIC 
LINE HAS FULL DUPLEX CAPABILITY 
TERMINAL HAS BINARY INPUT (DO NOT 
RECOGNIZE IMMEDIATE CONTROL CHARS) 
TERMINAL IS REMOTE (CONNECTED VIA MODEM) 
ACCEPT 8-BIT CHARACTERS 

PASS 8 BITS ON READ PASS ALL 

TYPE-AHEAD BUFFER CHARACTER COUNT 
CONTROL-S STATE 

ESCAPE SEQUENCES ARE ANSI FORMAT 

ONLY PASS CTRL/S,Q ON READ PASS ALL 
ONLY PASS CTRL/S,QO,C ON REAL PASS ALL 
REMOTE ANSWER SPEED 

AUTO-BAUD SPEED DETECTION 

TYPEAHEAD BUFFER SIZE 

TYPEAHEAD BUFFER MODE (TASK OR CLI) 
DON'T BROADCAST TO THIS TERMINAL 
ANCILLARY CONTROL DRIVER 

AUTOANSWER RING COUNT 

SET DIALING TRANSLATE TABLE 

MAINTENANCE MODE 


WO On 


FRAME SIZE, DATA BITS + PARITY BIT (IF ANY) 


DIALING MODE (TONE, PULSE, ...-) 

DATA MODE (SERIAL, CODEC, VOICE, DTMF) 
DTMF TONE LENGTH (10MS MULTIPLES) 

DTMF INTERDIGIT LENGTH 

MODEM TYPE 

SET DTMF ESCAPE SEQUENCE 

AUX KEYBOARD INTERPRETATION EN/DISABLE 
GO VOICE (I.E. DELAY LOSS OF CARRIER 
DISCONNECT) 

MONITOR LINE (TURN TMS SPEAKER ON/OFF) 
HARDWARE SILENCE TIMEOUT (SECONDS) 
ANSI CRT TERMINAL 

VT1LOO-FAMILY TERMINAL DISPLAY 

DIGITAL CRT TERMINAL 

LOCAL TERMINAL EDITING 

REGIS GRAPHICS 


HANDLE ~C (OR INT-DO) DIFFERENTLY FOR IO.RTT 


FOR P/OS 
INDICATE CLI SHOULD GET ~C NOTIFICATION 


THIS MUST BE ONE GREATER THAN THE HIGHEST 


VALUE USED FOR A SYMBOL 


SET CHARACTERISTIC ERROR CODES 
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SE.ICN 
SE.FIX 
SE.BIN 
SE.VAL 
SE.TER 
SE.SPD 
SE.SPL 
SE.PAR 
SE.LPR 
SE.NSC 


SE.UPN 
SE.NIH 


of 


Seg we WS 


SF.SSC 
SF .SMC 
SF.RDF 
SF.STT 
SE sols 
SF.GSC 
SF .GMC 
SF.GAC 
SF .SAC 


SF.DEF 


S.2400 
S.3600 
S.4800 


Oo OAD UI PW ND FE 


2400!020 
2400!040 
2400!060 
2400!100 
2400!120 
2400!140 
2400!160 
2400!200 
2400!220 


010 


>; NOW THE SPEED TYPES 


TTSYMS 


ILLEGAL CHARACTERISTIC NAME 

ATTEMPT TO CHANGE FIXED CHARACTERISTIC 
ILLEGAL VALUE FOR BINARY CHARACTERISTIC 
ILLEGAL VALUE FOR NON-BINARY CHARACTERISTIC 
ILLEGAL TERMINAL TYPE 

ILLEGAL SPEED FOR INTERFACE 

ILLEGAL SPLIT SPEED FOR INTERFACE 
ILLEGAL PARITY TYPE FOR INTERFACE 

OTHER ILLEGAL LINE PARAMETERS 

INTERFACE DOES NOT HAVE SETTABLE 
CHARACTERISTICS 

NO SPACE TO SAVE DEFAULT CHARACTERISTICS 
CHARACTERISTIC NOT ASSEMBLED IN HANDLER 


NOW THE SUBFUNCTION CODES FOR THE SET CHARACTERISTICS FUNCTION 


SET SINGLE CHARACTERISTIC 
SET MULTIPLE CHARACTERISTICS 
RESTORE DEFAULT 

SET TERMINAL TYPE 

SET TERMINAL TYPE AND SPEED 
GET SINGLE CHARACTERISTIC 
GET MULTIPLE CHARACTERISTICS 
GET ALL CHARACTERISTICS 

SET ALL CHARACTERISTICS 


SET DEFAULT CHARACTERISTICS 
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S./200 
S.9600 
SEXTA 
S -EXTB 
owl eZ 
S.38.4 


-- 


~e@ BE Tr) 


T.UNKO 
T.AS33 
T.KS33 
T.AS35 
T.L308S 
T.L30P 
T.LA36 


T.VTO5 . 


T.VT50 
PaViloZ 
T.VT55 
T.VT61l 
T.L180 
T.V1O00 
T.L120 
T.SCRO 
T.LA12 
T.L100 
T.LA34 
T.LA38 
T.V1OL 
T.V1O2 
TeV1O5 
T.V125 
TeV deo 
T.V132 
T.LA5O 
T.LOPI 
T.LOP2 
T.BMPL 
T.USRO 
T.USRI1 
TeUSR2 
T.USR3 
T.USR4 


; DIAL 


XAT.DIA 
XT.DTM 


17 
18 
Lo 
20 
21. 
22s 


28 


T.-USRO+1 
T.USR1I+1 
T.USR2+1 
T.USR3+1 


MODES 


0 
1 


TTSYMS 


21. 
Zoe 
23% 
24. 
25 19.2KBPS 
26 38.4KBPS 


NOW THE TERMINAL TYPES 


@) UNKNOWN (UNSPECIFIED) 
1 ASR33 

2 KSR33 

3 ASR35 

4 LA30S 

5 LA30P 

6 LA36 

7 VTO5 

10 VT50 

Ta VT52 

2 VT55 

13 VT61 

1:4 LA180S 

15 VT100 

16 LA120 

Ly SCRIPT LINE 
20 GAL2 

21 LA100 

22 LA34 

23 LA38 

24 VTLO1 

25 VT102 

26 VT105 

27 VT125 

30 VEL31 

31 VT132 

32 LA50 

33 LOP I 

34 LOP II 

35 BIT MAP TERMINAL #1 (ORIGINAL PRO 350) 
200 USER TERMINAL 


USER TERMINAL 
USER TERMINAL 
USER TERMINAL 
USER TERMINAL 


Hm WN Fe © 


0 DIAL PULSE, 10 PULSES PER SEC 


1 DTMF 
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XT. D20 2 2 DIAL PULSE, 20 PULSES PER SEC 
XT.OHS 3 3 OFF-HOOK SERVICE (EXTERNAL FIXED NUMBER) 
° DATA MODES 

XT.VOI 0 0 VOICE TELEPHONE (NO DATA) 

XT.SER 1 1 SERIAL DATA 

XT.ENC 2 2 ENCODED VOICE 

XT.DTD 3 3 DTMF DATA 

° MODEM TYPE 

XTM.NO —l. 177777 NO MODEM, HARD-WIRED LINE 

XTM.FS 0 US FSK, 0..300 BAUD BELL 103 
XTM.PS 1 1 US DPSK, 1200 BAUD BELL 212 
XTM.21 5 5 CCITT V.21, 0..300 BAUD EUROPEAN 
XTM.M1 6 6 CCITT V.23 MODE 1, 75/0..600 
XTM.M2 7 7 CCITT Vi23: MODE: 2, 7570«.1200 
XTM.US 10: 12 MICRO-SWITCH 


; UNSOLICITED EVENT TYPES 


XTU.UI 0 0 UNSOLICITED INPUT 

XTU .CD 2 2 CARRIER DETECT NOTIFICATION 
ATU.CL él a ARRIER LOSS 

XATU.DR 6 6 DTMF ESCAPE SEQUENCE RECEIVED 
ATU .OF 8. 10 XOFF RECEIVED 

XTU .ON 10. 12 XON RECEIVED 

XTU.RI 12. 14 RING 

ATU. TU 14. 16 TELSET OFF HOOK 

XTU.TD 16. 20 TELSET ON HOOK 


BITS FOR RETURN FROM 'GET TERMINAL SUPPORT' 


=e@ BSG WES 


BIT MASK 
F1.ACR 000001 AUTO CR/LF ON LONG LINES 
F1l.BIW 000002 BREAK THROUGH WRITE 
F1l.BUF 000004 INTERMEDIATE BUFFERING 
F1.UIA 000010 UNSOLICITED INPUT AST‘S 
F1.CCO 000020 CANCEL CTRL-O ON WRITE 
F1l.ESO 000040 ESCAPE SEQUENCE SUPPORT 
Fl.HLD 000100 HOLD SCREEN SUPPORT 
F1.LWC 000200 LOWER CASE CONVERSION 
F1l.RNE 000400 READ NO ECHO 
F1.RPR 001000 READ WITH PROMPT 
F1l.RST 002000 READ WITH SPECIAL TERMINATORS 
Fl] .RUB 004000 SCOPE RUBOUTS 
F1.SYN 010000 XON/XOFF 
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Fl .TRW 
F1.UTB 
Fl .VBF 
F2.SCH 
F2.GCH 
F2.DCH 
F2.DKL 
F2.ALT 
F2.SFF 
F2.CUP 
F2.FDX 


=e a2e BWE =e 


TP eRoL 
TF .BIN 
TF .RAL 
TF .RNE 
TF .RNC 
TF .XOF 
TF .TMO 
TF .RCU 
TF .WAL 
TF .WMS 
TF eco 
TF .WBT 
TF.SYN 
TF .XCC 
TE .NOT 
TE .AST 
TF .ESQ 
TF .UCH 


020000 
040000 
100000 
000001 
000002 
000004 
000010 
000020 
000040 
000100 
000200 


001 
002 
010 
020 
040 
100 


TTSYMS 


TRANSPARENT READ/WRITE 

BUFFERING IN TASK BUFFER 

EXEC BUFFERS ARE VARIABLE LENGTH 
SET CHARACTERISTICS 

GET CHARACTERISTICS 

DUMP/RESTORE CHARACTERISTICS 
HISTORICAL 11D/IAS IO.KIL 
ALTMODE IS ECHOED 

FORMFEED CAN BE SIMULATED 

DEVICE INDEPENDENT CURSOR POSITIONING 
FULL DUPLEX TERMINAL DRIVER 


SUBFUNCTION BITS FOR TERMINAL HANDLER QIO'S. NOTE THAT THIS 
MUST REFLECT THE REALITY IN QIOMAC.MAC. 


[IO.RLB/IO.RPR] READ WITH SPECIAL TERMINATORS 
SEND PROMPT AS 'PASS ALL’ 
READ PASS ALL 
READ WITH NO ECHO 
READ WITH NO CASE CONVERSION 
SEND XOF AFTER PROMPT 
READ WITH TIMEOUT 

[IO.WLB] RESTORE CURSOR POSITION 
WRITE PASS ALL 
WRITE SUPPRESSIBLE MESSAGE 
CANCEL CONTROL-O 
BREAK THROUGH READ 
SYNCHRONOUS WRITE (IAS ONLY) 

[IO.ATT] DO NOT TRAP CONTROL-C 

NOTIFICATION ONLY FOR TYPE-AHEAD 
SPECIFY AST'S IN ATTACH 
RECOGNIZE ESCAPE SEQUENCES 
CHARACTER AST NOTIFICATION (IAS) 
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A.17 


000000 
000002 
000003 
000004 
000006 
000012 
000016 
000022 
000026 
000030 
000032 
000034 
000036 
000040 
000041 
000044 
000046 
000050 


000052 
000054 
000060 
000062 
000063 
000064 
000065 
000066 
000072 
000074 
000076 
000077 


000100 
000104 
000110 
000112 


000114 
000116 


4. 


TASK 


ze ™=6@ ~@ BZ BWS 


T.1OCs 


T.PCBV: 


TeNAM: 


TeRCVL 
T.ASTL: 
Tee oGe 


T<UCB: 


TeITrCBL: 
T.STAT: 


tawolz: 
Teot3s 


T.DPRI: 


T.LBN: 
T sLDV: 
T.PCB: 


T.MXSZ: 


T.ACTL: 


T- ATT: 
t.ST4s 


T .HDLN : 


T.GGF: 
Te LLOe 


T EFLM: 
LelKoOS: 


T-OFF': 


TeoRC Ts 


TwRREGS 
TsOCBH: 
LeRDCT? 
TseoASt: 


$$$ = 


T.RRM: 
T.IRM: 


TCBDFS,,SYSDF 


eASECT 


e BLKW 
e BLKB 
e BLKB 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKB 
eBLKB 
« BLKW 
e BLKW 
e BLKW 


e BLKW 
e BLKW 
- BLKW 
eBLKB 
e BLKB 
eBLKB 
- BLKB 
eBLKW 
» BLKW 
e BLKW 
- BLKB 
e BLKB 


e BLKW 
e BLKW 
e BLKW 
e BLKW 


eIF NB 


e BLKW 
- BLKW 


TCBDFS$ , ,SYSDF 


CONTROL BLOCK 


ee ee Oe en Cn ee ee 


ee Oe ee en eee 


Mr hd 


SYSDF 


1 
J 


TASK CONTROL BLOCK OFFSET AND STATUS DEFINITIONS 


sUTILITY LINK WORD 

*>TASK PRIORITY 

>I/O PENDING COUNT 

*POINTER TO COMMON PCB VECTOR 
°TASK NAME IN RAD50 

*RECEIVE QUEUE LISTHEAD 

*-AST QUEUE LISTHEAD 

TASK LOCAL EVENT FLAGS 1-32 
UCB ADDRESS FOR PSEUDO DEVICE 
°TASK LIST THREAD WORD 

;FIRST STATUS WORD (BLOCKING BITS) 
SECOND STATUS WORD (STATE BITS) 
*THIRD STATUS WORD (ATTRIBUTE BITS) 
*TASK'S DEFAULT PRIORITY 

*LBN OF TASK LOAD IMAGE 

UCB ADDRESS OF LOAD DEVICE 

-PCB ADDRESS OF TASK PARTITION 
*>MAXIMUM SIZE OF TASK IMAGE (MAPPED 
*ONLY) 

ADDRESS OF NEXT TASK IN ACTIVE LIST 
*ATTACHMENT DESCRIPTOR LISTHEAD 
-FOURTH TASK STATUS WORD 

e-LENGTH OF HEADER (0 IF HDR IN POOL) 
* UNUSED 

*>GROUP GLOBAL USE COUNT FOR TASK 
*BUFFERED I/O IN PROGRESS COUNT 
>TASK WAITFOR MASK/ADDRESS 

*TASK LOAD SIZE IN 32 WD BLOCKS 
*OFFSET TO TASK IMAGE IN PARTITION 

> RESERVED 

*>SREF WITH EFN COUNT IN ALL RECEIVE 
*QUEUES 

*>RECEIVE BY REFERENCE LISTHEAD 
*>OFFSPRING CONTROL BLOCK LISTHEAD 
*>OUTSTANDING OFFSPRING AND VT: COUNT 
*>SPECIFY AST LIST HEAD 


so Ha 


*REQUIRED RUN MASK (NOT USED) 
> INITIAL RUN MASK SET UP BY INSTALL 
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- (NOT USED) 
000120 T.CPU: .BLKB aI *PROCESSOR NUMBER ON WHICH TASK LAST 
* EXECUTED 
000121 ~BLKB 1 ° (UNUSED) 
o=SSS 
SSS=. 


T.ACN: »-BLKW 1 ;POINTER TO ACCOUNTING BLOCK 


-IF NDF ASSCNT ;NOT CURRENTLY USED 
-=S$$ 

» ENDC 
SS$=. 
T.ISIZ: .BLKW 1 ;SIZE OF ROOT I SPACE 


IF NDF USSDAS 


o=SSS 
»ENDC ° NDF USSDAS 
T<LGTH=. °LENGTH OF TASK CONTROL BLOCK 
T.EXT=0 LENGTH OF TCB EXTENSION 
~IFF 
-- 


TASK STATUS DEFINITIONS 


@2=O@ @=@ Be BE =~ @ 


FIRST STATUS WORD (BLOCKING BITS) 


TS .EXE=100000 *TASK NOT IN EXECUTION (1=YES) 

TS .RDN=40000 *I/O RUN DOWN IN PROGRESS (1=YES) 

TS .MSG=20000 *>ABORT MESSAGE BEING OUTPUT (1=YES) 

TS .CIP=10000 *TASK BLOCKED FOR CHECKPOINT IN PROGRESS 
°(1=YES) | | 

TS.RUN=4000 *TASK IS RUNNING ON ANOTHER PROCESSOR (1=YES) 

TS.STP=1000 *TASK BLOCKED BY CLI COMMAND 

TS .CKR=100 *>TASK HAS CKP REQUEST (MP SYSTEM ONLY) (1=YES) 

TS.BLC=37 * INCREMENT BLOCKING COUNT MASK 
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; SECOND STATUS 


T2.AST=100000 
T2.DST=40000 
T2.CHK=20000 


T2.REX=10000 
T2.SEF=4000 
T2.SIO=1000 
T2.AFF=400 
T2.HLT=200 
T2 -<ABO=100 
T2.STP=40 
T2 -STP=20 
T2.SPN=10 
T2-SPN=4 
T2.WFR=2 
T2.WFR=1 

a 


Zee BWEe 


T3.-ACP=100000 
T3.PMD=40000 
T3.REM=20000 
T3.PRV=10000 
T3.MCR=4000 


T3.SLV=2000 
T3.CLI=1000 
T3.RST=400 
T3 .NSD=200 
T3.CAL=100 
T3 .-ROV=40 
T3.NET=20 
T3 ..MPC=10 
T3 .CMD=4 
T3.SWS=2 


TCBDF$ , ,SYSDF 


STATUS MASK 


WORD (STATE BITS) 


>AST IN PROGRESS (1=YES) 

AST RECOGNITION DISABLED (1=YES) 

>TASK NOT CHECKPOINTABLE(1=YES,SEE PCB AS 
°WELL) 

*REQUESTED EXIT AST SPECIFIED 
;TASK STOPPED FOR EVENT FLAG(S) 
;TASK STOPPED FOR BUFFERED I/O 
*TASK IS INSTALLED WITH AFFINITY 
*TASK IS BEING HALTED (1=YES) 
>TASK MARKED FOR ABORT (1=YES) 
*>SAVED T2.SPN ON AST IN PROGRESS 
*TASK STOPPED (1=YES) 

*>SAVED T2.SPN ON AST IN PROGRESS 
*TASK SUSPENDED (1=YES) 

>SAVED T2.WFR ON AST IN PROGRESS 
*TASK IN WAITFOR STATE (1=YES) 


(1=YES) 


THIRD STATUS WORD (ATTRIBUTE BITS) 


*ANCILLARY CONTROL PROCESSOR (1=YES) 
*DUMP TASK ON SYNCHRONOUS ABORT (0=YES) 
*>REMOVE TASK ON EXIT (1=YES) 

*TASK IS PRIVILEGED (1=YES) 

*TASK REQUESTED AS EXTERNAL MCR FUNCTION 
-(1=YES) 

*TASK IS A SLAVE TASK (1=YES) 


*>TASK IS A COMMAND LINE INTERPRETER (1=YES) 
*TASK IS RESTRICTED (1=YES) 

*TASK DOES NOT ALLOW SEND DATA 

>TASK HAS CHECKPOINT SPACE IN TASK IMAGE 
eTASK HAS RESIDENT OVERLAYS 


;NETWORK PROTOCOL LEVEL 

;MAPPING CHANGE WITH OUTSTANDING I/O (1=YES) 
;TASK IS EXECUTING A CLI COMMAND 

>RESERVED FOR SPM-11, (NOT AVAILABLE ON P/OS, 
>THIS BIT HAS BEEN TEMPORARILY REDEFINED ON 
-V1.7 AND V2.0 TO IDENTIFY APPLICATION TASKS 
>FROM SYSTEM TASKS. THE FORMER ARE REMOVED 
;WHEN APPLICATION EXITS. IT IS SOMETIMES 
;REFERRED TO AS THE "BEAT ME" BIT. 
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T3.GFL=1 ;GROUP GLOBAL EVENT FLAG LOCK 


4. 
STATUS BIT DEFINITIONS FOR FOURTH STATUS WORD (T.ST4) 


~™e WS =e 


T4.VCT=100 ;TASK HAS BEEN VICTIMIZED (BLASTED) 

T4 .MUT=40 ;TASK IS A MULTI-USER TASK (MEANING SEPARATED 
;READ ONLY AND READ/WRITE FOR TASK REGION. THIS 
;HAS PERFORMANCE ADVANTAGES OVER A NON MU TASK 
;AND IS FULLY SUPPORTED ON P/OS) 


T4.LDD=20 ;TASK’S LOAD DEVICE HAS BEEN DISMOUNTED 
T4.PRO=10 ;TCB IS (OR SHOULD BE) A PROTOTYPE 
T4.PRV=4 ;TASK WAS PRIV, BUT HAS CLEARED T3.PRV 
;WITH GIN (MAY RESET WITH GIN IF T4.PRV SET) 
T4.DSP=2 ;TASK WAS BUILT FOR USER I/D SPACE 
T4.SNC=1 ;TASK USES COMMONS FOR SYNCHRONIZATION 
-- 


~™®,H BH WH 


REQUIRED RUN MASK 


TR.UBT=100000 ;UNIBUS RUN T 
TR.UBS=40000 ;UNIBUS RUN S 
TR.-UBR=20000 ;UNIBUS RUN R 
TR.-UBP=10000 ;UNIBUS RUN P 
TR.UBN=4000 ;UNIBUS RUN N 
TR.UBM=2000 ;UNIBUS RUN M 
TR.-UBL=1000 ;UNIBUS RUN 
TR.UBK=400 ;UNIBUS RUN K 
TR.UBJ=200 ;UNIBUS RUN J 
TR.UBH=100 ;UNIBUS RUN H 
TR.UBF=40 ;UNIBUS RUN F 
TR.UBE=20 ;UNIBUS RUN E 
TR.CPD=10 ; PROCESSOR D 
TR.CPC=4 ; PROCESSOR C 
TR.CPB=2 ; PROCESSOR 
TR.CPA=1 ; PROCESSOR A 

e ENDC 

«PSECT 
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A.18 


abe 


—™@ ~WSE WE WH WE WE WH WS WE BWH WHE WE WH WS 


e=177770 


U.UAB: 


U.UAB: 


177772 


177774 
177776 
000000 
000002 
000004 
000005 
000006 
000007 
000010 
000012 
000014 
000016 
000020 


eASECT 


elF NB 


eIF DF 


e BLKW 


oLlFF 


e ENDC 


eENDC 


U.MUP: 


U.LUIC: 


U .OWN : 
U.DCB: 
Us REDS 
U.~CTL: 
U.STS 


U.UNIT: 


UsST 2: 
U.CWl: 
U.CW2: 
U.CW3: 
U.CW4: 
UsSCB? 


UNIT CONTROL BLOCK 


SYSDEF 


ASSCNT 


e BLKW 


e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKB 
eBLKB 
eBLKB 
e BLKB 
e BLKW 
e BLKW 
e BLKW 
e BLKW 
e BLKW 


UCBDFS , , TTDEF ,SYSDEF 


UCBDFS , , TTDEF,SYSDEF 


THE UNIT CONTROL BLOCK (UCB) DEFINES THE STATUS OF AN 
INDIVIDUAL DEVICE UNIT AND IS THE CONTROL BLOCK THAT IS POINTED 
TO BY THE FIRST WORD OF AN ASSIGNED LUN. THERE IS ONE UCB FOR 
EACH DEVICE UNIT OF EACH DCB. THE UCB’S ASSOCIATED WITH A 
PARTICULAR DCB ARE CONTIGUOUS IN MEMORY AND ARE POINTED TO BY 
THE DCB. UCB'S ARE VARIABLE LENGTH BETWEEN DCB'S BUT ARE OF THE 
SAME LENGTH FOR A SPECIFIC DCB. A UCB EXISTS FOR EVERY LOGICAL 
UNIT ON THE SYSTEM AND DEFINES UNIT CHARACTERISTICS AS WELL AS 
CURRENT UNIT STATUS. 


>POINTER TO USER ACCOUNT BLOCK (DV.TTY ONLY) 


oom 


Fd pe pe et YO 


(-6) MULTI-USER PROTECTION WORD (DV.TTY 
ONLY) 

°(-4) LOGIN UIC (DV.TTY ONLY) 

-(-2) OWNING TERMINAL( DEVICE ALLOCATION) 
*>BACK POINTER TO DCB 

*POINTER TO REDIRECT UNIT UCB 

*CONTROL PROCESSING FLAGS 

*-UNIT STATUS 

*PHYSICAL UNIT. NUMBER 

UNIT STATUS EXTENSION 

*FIRST DEVICE CHARACTERISTICS WORD 
*SECOND DEVICE CHARACTERISTICS WORD 
*THIRD DEVICE CHARACTERISTICS WORD 
>FOURTH DEVICE CHARACTERISTICS WORD 
*>POINTER TO SCB 


= @ = 6 
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000022 
000024 
000026 
000030 


000032 
000034 
000036 
000032 
000040 
000042 
000046 
000050 
000046 
000050 
000052 


000054 
000060 


000062 


000064 


000040 
000042 
000044 


000000 
000022 
000026 
000032 
000033 
000034 
000035 
000036 


UCBDFS, , TTDEF ,SYSDEF 


U.ATT: » BLKW 1 ;TCB ADDRESS OF ATTACHED TASK 

U.BUF: e BLKW 1 ;RELOCATION BIAS OF CURRENT I/O REQUEST 
e BLKW 1 ;BUFFER ADDRESS OF CURRENT I/O REQUEST 

U.CNT: e BLKW 1 ;BYTE COUNT OF CURRENT I/O REQUEST 


° (DV.MSD) 

*>BIAS OF UCB EXTENSION IN SEC POL 
*ADDRESS OF TCB OF MOUNTED ACP 

*ADDRESS OF VOLUME CONTROL BLOCK 

*CONTROL BUFFER RELOCATION AND ADDRESS 
ADDRESS OF UMB FOR SHADOW RECORDING 
*DISK SIZE PARAMETER WORDS 

UNIT COMMAND TIME OUT 

UNIT OUTSTANDING I/O PACKET LISTHEAD 
CSR ADDRESS (P/OS Vl DRIVER ACCESS ONLY) 
>SLOT NUMBER (P/OS V1 DRIVER ACCESS ONLY) 
°4 WD SAVED I/O PACKET AREA (DV.MSD AND 

> USAGE 


U.UCBX=U .CNT+2 
U.ACP=U .CNT+4 
U.VCB=U .CNT+6 
U.CBF=U.CNT+2 
U.UMB=U.CNT+10 
U.PRM=U.CNT+12 
U.-UTMO=U .CNT+16 
U.LHD=U..CNT+20 
U.-ICSR=U.CNT+16 
U.SLT=U.CNT+20 
U.SPRM=U .CNT+22 


;OF SVOLSC) USED AT I/O COMPLETION TO RESTORE 
;I1/O PACKET IF STALLED I/O CONDITION IN EFFECT) 


;UNIT BAD BLOCK PACKET WAITING LIST 
;POINTER TO SECOND EXTENSION IN 

; SECONDARY POOL | 
;OUTSTANDING COMMAND STATUS REQUEST 
;REGISTER 

;COMMAND STATUS PROGRESS REGISTER 


U.BPKT=U .CNT+24 
U.UC2X=U .CNT+30 


U .OTRF=U .CNT+32 


U.CMST=U .CNT+34 


MAGTAPE DEVICE DEPENDANT UCB OFFSETS 


~™Ee ~~ we 


;SLAVE UNIT NUMBER 
; FUNCTION CODE 
;SUBCONTROLLER KRB1 POINTER 


v 


U.SNUM=U.CNT+10 
U.FCDE=U.CNT+12 
U.-KRB1=U.CNT+14 


DEFINE SECONDARY POOL UCB EXTENSION OFFSETS 
(DV.MSD DEVICES ONLY) 


e @2~6 =e BSH BWS 


=0 
- BLKW 9.:;FIXED ACCOUNTING TRANSACTION HEADER 

X-NAME: .BLKW 2 ;DRIVE NAME IN RAD5O 
X.I0C: .BLKW 2 :I/O COUNT 
X.ERHL: ~.BLKB 1 ;HARD ERROR LIMIT 
X.-ERSL: .BLKB 1 ;SOFT ERROR LIMIT 
X.-ERSC: .BLKB 1 ;SOFT ERROR COUNT 
X.ERHC: .BLKB 1 ;HARD ERROR COUNT 
X.WCNT: .~BLKW 2 ;WORDS TRANSFERED COUNT 


A-72 


000042 
000046 
000050 
000051 
000051 


000052 
000054 
000055 
000056 
000012 
000010 
000005 


000000 
000002 
000004 
000010 
000020 
000024 
000026 
000030 
000032 
000034 
000036 
000037 
000040 
000042 
000043 


000044 
000050 


UCBDFS , , TTDEF,SYSDEF 


DEFINE OFFSETS FOR SEEK OPTIMIZATION DEVICES 


~e@ WE a) 


XeCYLC: .~BLKW 
Xe-CCYL: .~BLKW 


7;CYLINDERS CROSSED COUNT 
CURRENT CYLINDER | 

X-eFCUR: .~BLKB ;CURRENT FAIRNESS COUNT 

XAeFLIM: ;FAIRNESS COUNT LIMIT 

X~eDSKD: .BLKB 1 ;DISK DIRECTION (HIGH BIT 1=OUT) 


rr NO 


XeDNAM: .~BLKW 1 ;DEVICE NAME FOR ACCOUNTING 
XeUNIT: .BLKB 1 ;UNIT NUMBER FOR ACCOUNTING 
1 


e BLKB ;UNUSED FOR NOW 
Xe LGTH=. ;LENGTH OF THE UCB EXTENSION 
X.-DFFL=10. ;DEFAULT FAIRNESS COUNT LIMIT 
X-DFSL=8. ;DEFAULT SOFT ERROR LIMIT 
X.-DFHL=5. ;DEFAULT HARD ERROR LIMIT 


DEFINE OFFSETS FOR DISK MSCP CONTROLLERS (SECOND UCB 
EXTENSION) 


~P WE We or) 


CHARACTERISTICS OBTAINED FROM "GET UNIT STATUS" END 
PACKETS 


we we WH % @ 


-=0 


XeUSVR: ~.~BLKB 
XeUHVR: .BLKB 
XeRCTS: .~BLKW 
X-eRBNS: .BLKB 
XeRCTC: .~BLKB 


;UNIT SOFTWARE VERSION 
UNIT HARDWARE VERSION 
;UNIT RCT TABLE SIZE 
;UNIT RBN 'S / TRACK 
-UNED RCT ‘COPIES 


XAeMLUN: .BLKW 1 ;MULTI-UNIT CODE 
XAeUNFL: .~BLKW 1 ;UNIT FLAGS 
» BLKW 2 ;RESERVED 

XeUNTI: .~BLKW 4 ;UNIT IDENTIFIER 
XeMEDI: .~BLKW 2 ;MEDIA IDENTIFIER 
XeSHUN: .BLKW 1 ;SHADOW UNIT 
XeSHST: .~BLKW 1 ;SHADOW UNIT STATUS 
Xe-TRCK: .~BLKW 1 ;UNIT TRACK SIZE 
XeGRP: e BLKW 1 ;UNIT GROUP SIZE 
XeCYL: » BLKW 1 ;UNIT CYLINDER SIZE 

i, 

1. 

1 

1 

i 


CHARACTERISTICS OBTAINED FROM "ONLINE" OR "SET UNIT 
CHARACTERISTICS" END PACKETS 


®@ we BE WE 


XeUNSZ: .~BLKW 2 ;UNIT SIZE 
XeVSER: .~BLKW 2 ;VOLUME SERIAL NUMBER 
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000054 


000024 
000026 
000036 
000040 
000041 
000042 
000044 
000045 


000046 


000047 
000050 


000050 


000051 
000052 
000054 
000056 


X.-DUSZ=. 


@ wae Be =e 


=U.BUF 
Us FUX* 

U.TSTA: 
U,ULTC: 

U.TLPP: 
U.TFRO: 
Us TFiK: 
U.TCHP: 
U.TCVP: 
U.TTYP: 
U.TMTI: 
UsTIABs 


e=.-2 


Us TECO? 


UsrBSZs 
U.ACB: 

U.AFLG: 
U.ADMA: 


e@ ~=O@ Ee 


S1.RST=1 
S1.RUB=2 
S1.ESC=4 
S1.RAL=1 


UCBDFS,,TTDEF,SYSDEF 


SIZE OF DISK MSCP CONTROLLER UCB 
EXTENSION 


rs 
a 
® 
g 


eIF NB TTIDEF 


e BLKW 
- BLKW 
e BLKW 
-BLKB 
eBLKB 
e BLKW 
eBLKB 
-BLKB 
eBLKB 
e BLKB 
e BLKW 


e BLKB 


eBLKB 
e BLKW 
» BLKW 
e BLKW 


0 


S1.RNE=20 
S1.CTO=40 
S1.OBY=100 
S1.IBY=200 
S]1.BEL=400 
S1.DPR=1000 
S1.DEC=2000 


ee eee 


a 


DEFINE BITS IN STATUS WORD 


TERMINAL DRIVER DEFINITIONS 


*POINTER TO UCB EXTENSION (UCBX) 

STATUS QUADRUPLE-WORD 

*>DEFAULT UIC <====(ANY DV.TTY DEVICE) 

*>LINES PER PAGE 

*>FORK REQUEST BYTE 

*FORK LIST LINK WORD 

*CURRENT HORIZONTAL POSITION 

*>CURRENT VERTICAL POSITION 

*TERMINAL TYPE 

*>MODEM TIMER 

°IF O: U.TTAB+tl IS SINGLE-CHARACTER 
TYPE-AHEAD BUFFER, CURRENTLY EMPTY 

IF ODD: U.TTAB+tl IS SINGLE-CHARACTER TYPE- 
AHEAD BUFFER AND HOLDS A CHARACTER 

IF NON-O AND EVEN: POINTER TO MULTI- 
CHARACTER TYPE-AHEAD BUFFER 

THE NEXT TWO OFFSETS OVERLAP U.TTAB WHEN 
THE TYPE-AHEAD BUFFER IS IN 
SECONDARY POOL 

ECHO BUFFER FOR DMA OPERATIONS WHEN UCBX 
IS SECONDARY POOL AND THUS NOT 
MAPPED BY A UMR 

*TYPEAHEAD BUFFER SIZE 

ANCILLARY CONTROL DRIVER BLOCK ADDR 

ANCILLARY CONTROL DRIVER FLAGS WORD 

eANCILLARY CONTROL DRIVER DMA BUFFER 


=e BB BSH BSH BH WHE WH BHO WH WH WO 


1 (U.TSTA) 


*;READ WITH SPECIAL TERMINATORS IN PROGRESS 
>RUBOUT SEQUENCE IN PROGRESS (NON-SCOPE) 
7;ESCAPE SEQUENCE IN PROGRESS 

;READ ALL IN PROGRESS 

7ECHO SUPPRESSED 

;OUTPUT STOPPED BY CTRL-O 

;OUTPUT BUSY 

7INPUT BUSY 

;BELL PENDING 

;DEFER PROCESSING OF CHAR. IN U.TECB 
;DEFER ECHO OF CHAR. IN U.TECB 
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S1.DSI=4000 


S1.CTS=10000 
S1.USI=20000 
S1.OBF=40000 
S1.IBF=100000 


e@ =6@¢ Ee 


S2.ACR=1 
S2.WRA=6 
S2.WRB=2 
S2.CR=10 
S2.BRQ=20 
S2.SRQ=40 


S2.ORQ=100 
S2.IRQ=200 
S2.HFL=3400 
S2.VFL=4000 
S2.HHT=10000 
S2.HFF=20000 
S2.FLF=40000 


S2.FDX=100000 


UCBDFS, , TTDEF ,SYSDEF 


7; INPUT PROCESSING DISABLED 
;OUTPUT STOPPED BY CTRL-S 
;UNSOLICITED INPUT IN PROGRESS 
;BUFFERED OUTPUT IN PROGRESS 
7;BUFFERED INPUT IN PROGRESS 


DEFINE BITS IN STATUS WORD 2 (U.TSTA+2) 


;WRAP-AROUND (AUTOMATIC CR-LF) REQUIRED 
;CONTEXT FOR WRAP-AROUND 

;LOW BIT IN S2.WRA BIT PATTERN 

; TRAILING CR REQUIRED ON OUTPUT 

; BREAK~THROUGH-WRITE REQUEST IN QUEUE 
;SPECIAL REQUEST IN QUEUE 

; (IO.ATT, IO.DET, SF.SMC) 

;OUTPUT REQUEST IN QUEUE (MUST = S1.OBY) 
; INPUT REQUEST IN QUEUE (MUST = S1.IBY) 
;HORIZONTAL FILL REQUIREMENT 

;VERTICAL FILL REQUIREMENT 

; HARDWARE HORIZONTAL TAB PRESENT 
;HARDWARE FORM-FEED PRESENT 

;FORCE LINE FEED BEFORE NEXT ECHO 

;LINE IS IN FULL DUPLEX MODE 


DEFINE BITS IN STATUS WORD 3 (U.TSTA+4) 


S3.RAL=10 


S3.RPO=20 
S3 .WES=40 
S3.TAB=100 
S3.8BC=200 
S3.RCU=400 
S3.ABD=1000 
S3.ABP=2000 
S3.WAL=4000 
S3.VER=10000 


S3.BCC=20000 


S3 .DAO=40000 


S3.PCU=100000 


TERMINAL IS IN READ-PASS-ALL MODE 
°(S3.RAL MUST = S1.RAL) 

eREAD W/PROMPT OUTPUT IN PROGRESS 

*TASK WANTS ESCAPE SEQUENCES 
eTYPE-AHEAD BUFFER ALLOCATION REQUESTED 
*PASS 8 BITS ON INPUT 

eRESTORE CURSOR (MUST = TF.RCU*400) 
*AUTO-BAUD SPEED DETECTION ENABLED 
*>AUTO-BAUD SPEED DETECTION IN PROGRESS 
*>WRITE-PASS-ALL (MUST = TF.WAL*400) 
*>LAST CHAR. IN TYPE-AHEAD BUFFER 

*HAS PARITY ERROR 

*>LAST CHAR. IN TYPE-AHEAD BUFFER 

*>HAS FRAMING ERROR 

*LAST CHAR. IN TYPE-AHEAD BUFFER 

*HAS DATA OVERRUN ERROR 

sNOTE - THE 3 BITS ABOVE MUST CORRESPOND 
-TO THE RESPECTIVE ERROR FLAGS IN THE 
*HARDWARE RECEIVE BUFFER 

*POSITION CURSOR: BEFORE WRITE 


> DEFINE BITS IN STATUS WORD 4 (U.TSTA+6) 
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S4.INT=40 ;~C INT-DO HANDLED DIFFERENTLY FOR 
7IO.RTT ON P/OS 

S4.DLO=100 ;DIAL-OUT LINE (IMPLIES U2.RMT) 

S4.ANI=400 7;ANSI CRT TERMINAL 

S4.AVO=1000 ;VTLOO-FAMILY TERMINAL DISPLAY 

S4.BLK=2000 ;BLOCK MODE TERMINAL 

S4.DEC=4000 ;DIGITAL CRT TERMINAL 

S4.EDT=10000 7; TERMINAL HAS LOCAL EDITING FUNCTIONS 

S4.RGS=20000 7LERMINAL SUPPORTS REGIS GRAPHICS 

S4.CTC=40000 ; TERMINAL WANTS CLI TO HAVE “~C 
;NOTIFICATION 

eENDC 


VIRTUAL TERMINAL UCB DEFINITIONS 


we BS WH 


. -=U0.UNIT 
000006 U.OCNT: .BLKB 
°-=U.BUF 
000024 U.RPKT: .~BLKW 
000026 U.WPKT: .~BLKW 
000030 U.IAST: .~BLKW 
000032 U.OAST: .~BLKW 
000034 U.AAST: .~BLKW 


Joon! 


*OFFSPRING WITH THIS AS TI: 


*>CURRENT OFFSPRING READ I/O PACKET 
;CURRENT OFFSPRING WRITE I/O PACKET 
; INPUT AST ROUTINE ADDRESS 
;OUTPUT AST ROUTINE ADDRESS 
;ATTACH AST ROUTINE ADDRESS 


fd fd fed ft feet 


eIF NB TTDEF 


~LIF NE U.AAST+2-U.UIC ~-ERROR ;ADJACENCY ASSUMED 


» ENDC 


~=U.AAST+4 
000040 U.PTCB: -BLKW 1 ;PARENT TCB ADDRESS 


CONSOLE DRIVER DEFINITIONS 


) ~@me BO WS 


=U .BUF+2 
000026 U.CTCB: .~BLKW 1 ;ADDRESS OF CONSOLE LOGGER TCB 


000030 U.COTO: .~BLKW 2 ;I1/0 PACKET LIST QUEUE 
000034 U.RED2: .~BLKW l ;REDIRECT UCB ADDRESS 


»PSECT 
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ote 


DEVICE TABLE STATUS DEFINITIONS 


DEVICE CHARACTERISTICS WORD 1 (U.CWl) DEVICE TYPE 
DEFINITION 


~e@ ZOE WH WH BW ®& @ 


BITS. 

DV.REC=1 *RECORD ORIENTED DEVICE (1=YES) 

DV.CCL=2 *CARRIAGE CONTROL DEVICE (1=YES) 

DV. TTyY=4 *TERMINAL DEVICE (1=YES) 

DV.DIR=10 *>FILE STRUCTURED DEVICE (1=YES) 
DV.SDI=20 SINGLE DIRECTORY DEVICE (1=YES) 
DV.SQD=40 SEQUENTIAL DEVICE (1=YES) 

DV.MSD=100 *>MASS STORAGE DEVICE (1=YES) 

DV.UMD=200 USER MODE DIAGNOSTICS SUPPORTED (1=YES) 
DV.MBC=400 * RESERVED 

DV .EXT=400 > RESERVED 

DV.SWL=1000 UNIT SOFTWARE WRITE LOCKED (1=YES) 
DV.ISP=2000 * INPUT SPOOLED DEVICE (1=YES) 
DV.OSP=4000 OUTPUT SPOOLED DEVICE (1=YES) 
DV.PSE=10000 *PSEUDO DEVICE (1=YES) 

DV .COM=20000 > RESERVED 

DV.F11=40000 *>DEVICE IS MOUNTABLE AS F1l DEVICE (1=YES) 
DV .MNT=100000 *DEVICE IS MOUNTABLE (1=YES) 

-- 


TERMINAL (DV.TTY)DEPENDENT CHARACTERISTICS WORD 2 
(U.CW2) BIT DEFINITIONS 


e =e 6 


ee 


U2.DH1=100000 s>UNIT IS A MULTIPLEXER (1=YES) 


U2.DJ1=40000 sUNIT IS A DJ11l (1=YES) 

U2.RMT=20000 *UNIT IS REMOTE (1=YES) 

U2 .HFF=10000 *>UNIT DOES HRDWRE FORM FEEDS(1=YES) 
U2.L8S=10000 OLD NAME FOR U2.HFF 

U2 .NEC=4000 >DON'T ECHO SOLICITED INPUT (1=YES) 
U2.CRT=2000 eUNIT IS A CRT (1=YES, ANY DV.TTY IMPLIES 


-(DEL=BSP,SPC,BSP AND TERM TYP INDEPENDENT 
° CURS POSITIONING) ) 


U2.ESC=1000 *UNIT GENERATES ESCAPE SEQ.(1=YES,ANY DV.TTY) 
U2. LOG=400 >USER LOGGED ON TERMINAL (0=YES) (ANY DV.TTY) 
U2.SLV=200 sUNIT IS SLAVE TERM(1=YES) (RESRVD ANY DV.TTY) 
U2.DZ1=100 UNIT IS A DZ11 (1=YES) 
U2.HLD=40 -TERMINAL IS IN HOLD SCREEN MODE (1=YES) 
; (VT52) 
U2.AT.=20 ¢ (RESERVED) 
U2.PRV=10 -UNIT IS A PRIVILEGED TERM.(1=YES, ANY DV.TTY) 
U2.L3S=4 *-UNIT IS A LA30S TERMINAL (1=YES) 
U2.VT5=2 >UNIT IS A VTO5B TERMINAL (1=YES) 
U2.LWC=1 >LOWER CASE TO UPPER CASE CONVERSION ON INPUT 
> (O=YES) 
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-- 
BIT DEFINITIONS FOR U.MUP (NOT USED CURRENTLY, DV.TTY ONLY) 


=O WH 


UM.OVR=1 ;OVERRIDE CLI INDICATOR 

UM.CLI=36 ;CLI INDICATOR BITS 

UM.DSB=200 7TERMINAL DISABLED SINCE CLI ELIMINATED 

UM .NBR=400 7;NO BROADCAST 

UM.CNT=1000 ;CONTINUATION LINE IN PROGRESS 

UM.CMD=2000 ; COMMAND IN PROGRESS 

UM.SER=4000 7;SERIAL COMMAND RECOGNITION ENABLED 

UM.KIL=10000 ;TTDRV SHOULD SEND KILL PKT ON CNTRL/C 
“i 


TERMINAL SECONDARY POOL OFFSETS FOR THE UCB EXTENSION AND 
TYPEAHEAD BUFFER 


e 
g 
® 
g 
® 
g 
e 
g 

U 


- TAPR=24 ;OFFSET WITHIN UCB WHICH POINTS TO UCB 
: EXTENSION 
U.TTBF=46 ,;OFFSET WITHIN UCB EXTENSION WHICH POINTS 
; TO TYPEAHEAD BUFFER 
“+ 


TERMINAL DEPENDENT CHARACTERISTICS WORD 3 (U.CW3) BIT 
; DEFINITIONS 


U3.UPC=20000 ;UPCASE OUTPUT FLAG 
U3.PAR=40000 ; PARITY GENERATION AND CHECKING 
U3.OPA=100000 ;PARITY SENSE (1=ODD PARITY) 

-- 


VIRTUAL TERMINAL 3RD CHARACTERISTICS WORD DEFINITIONS 
(DRIVER SPECIFIC) 


U3%FDX=1 *-FULL DUPLEX MODE (1=YES) 

U3.DBF=2 * INTERMEDIATE BUFFERING DISABLED (1=YES) 
U3.RPR=4 eREAD W/PROMPT IN PROGRESS (1=YES) 

isa 

3: TERMINAL DEPENDENT CHARACTERISTICS WORD 4 (U.CW4) BIT DEF. 
° (DRIVER SPECIFIC) 

U4.CR=100 ©LOOK FOR CARRIAGE RETURN 

or 

* UNIT CONTROL PROCESSING FLAG DEFINITIONS 

UCL ALG=200 e-BYTE ALIGNMENT ALLOWED (1=NO) 

UC .NPR=100 “DEVICE IS AN NPR DEVICE (1=YES) 
UC.QUE=40 CALL DRIVER BEFORE QUEUING (1=YES) 

UC. PWF=20 CALL DRIVER AT POWERFAIL ALWAYS (1=YES) 
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UC .ATT=10 ;CALL DRIVER ON ATTACH/DETACH (1=YES) 
UC.KIL=4 ;CALL DRIVER AT I/O KILL ALWAYS (1=YES) 
UC.LGH=3 7; TRANSFER LENGTH MASK BITS 

=. 


we we 


UNIT STATUS BIT DEFINTIONS 


US.BSY=200 UNIT IS BUSY (1=YES) 
US .MNT=100 UNIT IS MOUNTED (0= YES)<=CAREFUL OF 
: POLARITY! 
US.FOR=40 UNIT IS MOUNTED AS FOREIGN VOLUME (1=YES) 
US. LAB=4 UNIT HAS LABELED TAPE ON IT (1=YES) 


°(HAS MEANING FOR DV.MNT AND 
: (US .MNT!US.FOR=0) ) 


US .MDM=20 *UNIT IS MARKED FOR DISMOUNT (1=YES) 
US .PWF=10 *POWERFAIL OCCURED (1=YES). 
= 


=e ~ e 


CARD READER DEPENDENT UNIT STATUS BIT DEFINITIONS 


US .ABO=1 UNIT IS MARKED FOR ABORT IF NOT READY 
; (1=YES) 
US .MDE=2 UNIT IS IN 029 TRANSLATION NODE (1=YES) 
2+ 
° DV.MSD DEPENDENT UNIT STATUS BITS 
US .WCK=10 eWRITE CHECK ENABLED (1=YES) 
US.SPU=2 UNIT IS SPINNING UP (1=YES) 
US.VV=1 *VOLUME VALID IS SET (1=YES) 


; TERMINAL DEPENDENT UNIT STATUS BIT DEFINITIONS 


US .CRW=4 *-UNIT IS WAITING FOR CARRIER (1=YES) 
US.DSB=2 *UNIT IS DISABLED (1=YES) 
US .OIU=1 OUTPUT INTERRUPT IS UNEXPECTED ON UNIT 
; (1=YES) 
ie 3 
> UNIT STATUS EXTENSION (U.ST2) BIT DEFINITIONS 
US .OFL=1 *UNIT OFFLINE (1=YES) 
US .RED=2 UNIT REDIRECTABLE (0=YES) 
US .PUB=4 *UNIT IS PUBLIC DEVICE (1=YES) 
US .UMD=10 *>UNIT ATTACHED FOR DIAGNOSTICS (1=YES) 
US .PDF=20 *PRIVILEGED DIAGNOSTIC FUNCTIONS ONLY 
: (1=YES) 
US .MUN=40 *>MULTI-UNIT FLAG 
US.TRN=100 sUNIT TRANSITION HAS OCCURRED (1=YES) 
US .S10=200 *>STALL I/O TO UNIT (1=YES) (ANY DEVICE) 
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UD.625=5 


e ENDM 


SUPPORT DEFINITION IN U.CW3 


=e 2G »™HG WH WH WO 
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UNSUPPORTED 
2Z00BPI, 7 TRACK 
556BPI, 7 TRACK 


SOOBPI, 7 OR 9 TRACK 


1600BPI, 
6250BPI, 
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9 TRACK 
9 TRACK 


APPENDIX B 


TASK BUILDING AND CLUSTER LIBRARIES 


This appendix provides an overview and examples of conceptual and 
detailed information on overlaying task structures and cluster 
libraries for PDP-11 and RSX systems. Note that the information is 
generic. For more detail, also see the Task Builder Manual. 


B.l1 AN OVERVIEW OF OVERLAYING 


This discussion of overlaying covers a complex subject. The RSX-11M 
PLUS Task Builder Manual provides more detail on the material covered 
here, plus information on the extended overlaying facilities that 
involve mapping via the PLAS directives and memory-resident libraries. 


The complexity of task structure on RSX and related PDP-11 systems 
reflects both the utility and the limitations of the system hardware 
and software. Over the years, users have found the PDP-1l a_ suitable 
base for increasingly ambitious applications. The sizes of these 
applications have grown far beyond the hardware's 16-bit (64 Kbyte) 
direct addressing capabilities. Therefore, task structure extensions 
have evolved to meet the increased addressing needs of such 
applications in as transparent a manner as possible. 


The focus for these extensions has been the PDP-11 Task Builder (TKB), 
which is a powerful, complex utility. The TKB utility is sometimes 
criticized for its complexity. Note, however, that it must support 
run-time transparency (by and large its mechanisms must be transparent 
to code execution), structural transparency (by and =Ilarge its 
Structures must continue to Support flexible handling of program 
sections), and performance requirements (whatever it does should not 
bring the task to its knees). Obviously, providing these level of 
support will require some assistance from the program's designer. The 
various DIGITAL products (e.g., language object-time systems, data 
management services like RMS and FCS, and the Forms Management System) 
each provide pre-packaged task configuration aids designed to make 
task-building as automated as possible. If application size requires 
further packaging efforts, however, the user must become more actively 
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involved in this process. The following overview supplements’ the 
detailed descriptions of overlaying in the RSX-11M PLUS Task Builder 
Manual. 


B.1l.1 Basic Overlay Concepts and Constraints 


When total program size grows beyond the virtual addressing limits of 
the task "envelope," some tradeoffs must be made. Arrangements must 
be made to allow currently-executing code and currently-accessed data 
to reside in virtual memory while currently-unneeded code and data 
reside elsewhere (typically on disk), and to allow the configuration 
of resident segments to change dynamically with changing demands. 


One way to accomplish the required tradeoff is with a "code cache" (in 
this discussion, data segments are included with program code, since 
even if are separated, they are treated analagously). Also, presume 
that developers generate code/data segments that are sufficiently 
small and modular to be easily moved, vector any external CALLS or 
data references into control structures that specify the module 
required, and finally, create a wholly-transparent software "paging" 
scheme along the lines of VAX hardware paging. 


Examining some of the difficulties with this approach will help 
explain the mechanism we actually use: 


1. The major problem is the data references. They cannot be 
"caught" without interpreting the entire instruction stream 
in software. This tends to defeat the purpose of the PDP-ll 
instruction set. Also, despite the advantages of "clean" 
inter-module data linkages, they shouldn't be absolutely 
mandatory. If they were, it would be necesary for us to 


detect cases in which pointers to external data (in data 
structures, the general registers, etc.) are passed as input 
arguments, and vector these references as well (possibly 
through multiple levels of indirection). 


The performance overhead (perhaps 100-to-1) of software 
instruction interpretation rules out mandatory "clean" 
inter-module data linkages. Also, the goal of reasonable 
coding transparency rules out the extremely strict rules on 
inter-module data references that we would need without’ such 
interpretation. The conclusion is that data, when present, 
Must always appear at the same virtual address. 


If the software Supports the "PC-relative" hardware 
addressing modes for external data, then code, when present, 
also must appear at the same virtual address. In fact, even 
without external data references it could be awkward for code 
to move around - consider the case of nested subroutines with 
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RETURN addresses on the stack. 


Having constant data addresses solves only half the 
interpretation problem. Structure conventions are needed, 


perhaps supported by semi-automated mechanisms, to ensure 


that the desired data is actually resident in virtual memory 
when it is referred to by an instruction. The instruction 
itself won't be able to verify this. 


Any conventions, of course, limit our flexibility for 
configuring overlaid data. To allow for special cases, we 
should consider providing an escape mechanism so that’ the 


user code can explicitly request a data segment be loaded 
prior to referring to it. 


Normal external CALL and JMP transfers of control can be 
intercepted fairly easily. TKB must resolve the 
destinations, and can route them through a loading routine 
that preserves the general registers and stack depth while it 
demand-loads the target code segment if it is not already 
resident. 


Given the lack of "save/restore condition codes" instructions 
in the hardware, trying to preserve them across CALL/JMP 
transfers of control would be difficult, and would increase 
instruction overhead during the transfer. Transfers should 
be as efficient as possible when the code segment is already 
resident. Since passing condition code information as an 
input argument to an external routine is fairly unusual, it 
should be viewed as a coding restriction. 


Returning condition codes as output from a CALLed routine is 
not unusual, however, and they should be preserved. The 
easiest way to ensure their preservation is to require that 
the CALLing routine remain resident while the target routine 
executes. In that way, the RETURN requires no_- special 
handling. 


Using this approach as described, not only optimizes 
CALL/RETURN linkage performance, but also solves the problem 
of how to re-load the CALLer transparently should it be 
displaced by the target routine. It isn't feasible to keep 
loading information describing the CALLer on the stack (since 
stack depth is frequently relevant to the target routine), 
and would have to maintain a special overlay run-time system 
stack for this purpose. Also, some routine linkages use the 
RETURN address as a pointer to in-line input arguments. Le 
would be best not to tamper with it. 
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4. Other less common transfer-of-control mechanisms include 
coroutines and tables containing external dispatch addresses. 
Some of the same issues mentioned above apply to them. as 
may be reasonable to restrict generality of support for such 
linkages, but be certain you understand what is entailed. 


5. Even creating vectoring information for just the external 
CALL/JMP references could result in very large vector tables, 
which in turn would increase pressure on the very virtual 
memory resources we are trying to conserve. Instead of 
"paging" on a module-by-module basis, it is better to provide 
a way of grouping related modules together’ so that (a) 
references that occur within the group need not be vectored 
at all (the group is “paged" as a unit), and (b) a single 
structure descriptor can serve the entire group (though 
individual vectors will still be needed for each entry point 
referred to externally). 


6. Another good reason to page related moduleS aS a group is 
that performance will degrade if many small modules are 
"paged" individually, as several short disk "read" operations 
typically take much longer than a_=e single long "read" of 
equivalent content. 


B.1.2 The Overlay Structure 
Our main implementation constraints so far are thus: 


® To support the way the hardware performs data references in 
executing instructions. When a given segment of code or data 
appears in the overlay cache area, it should always appear at 
the same virtual address. 


@® To support frequently-used subroutine linkage mechanisms. 
The CALLing routine should remain resident while the CALLed 
routine executes. 


@® To achieve reasonable performance. Groups of related modules 
should be pageable as single units ("overlay segments"). The 
vector table overhead is minimized, since purely intra-group 
references need not be vectored. 


B.1.2.1 Overlaying Code Segments - The requirement stated in Section 
B.l1 above that CALLers remain resident in the "code cache" while the 
target routine executes, plus the desirability of allowing CALLed 
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routines to be nested, means that the logical structure for organizing 
code segment overlays in virtual memory is a "tree". 


With such a tree structure, the "root" of the tree is not overlaid. 
It permanently resides at a fixed location in the task's virtual 
address space. Routines in the root may CALL routines in one of the 
multiple overlay segments in the first level above the root level. 
(They may of course CALL other routines in the root level as_ well.) 
When a Level 1 routine is CALLed in this manner, TKB has actually 
caused the CALL to be redirected to an "autoload vector" in the root 


segment. This vector passes a "Segment descriptor" address (in the 
root segment) plus the virtual address of the target routine within 
that segment to a common "“autoload" routine in the root segment's 


overlay run-time system. This system uses the segment descriptor 
information to load the segment into virtual memory, if it is not 
already resident, and then passes control to the real target routine 
as if it had been CALLed directly. 


One autoload vector can service all references from the root to a 
Single Level 1 routine. A single such segment descriptor can service 
all references to all routines in a single Level 1 overlay segment. 


Each routine in Level 1 may in turn CALL routines in the overlay 
segments directly above its segment in the second level of the 
structure, as well as routines in its own overlay segment. Each Level 
1 to Level 2 CALL is’ similarly redirected through an appropriate 
autoload vector, which resides in the Level 1 segment rather than in 
the root. Therefore, use of valuable non-overlaid virtual memory 
space in the root will not be affected. 


Note that while a routine in the root may CALL routines in any Level l 
segment, a Level 1 routine may CALL only the sub-set of Level 2 
routines directly above its segment. Other Level 2 routines’ (and 
routines in other Level 1 segments) are inaccessible and invisible to 
it, because of the "CALLer must remain resident" requirement that led 
to the tree structure and the rules for its use. 


A sample 4-level overlay tree is diagrammed below. Each entity marked 
with brackets [] (except the root) represents an overlay segment 
containing potentially multiple routines in multiple modules. The 
segment names are arbitrary, but useful, for the discussion. 
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Level 3 cae a we al 
\ / 
Level 2 [AA] [AB] [BA] [BB] [Bc] [BD] rCA). [CBi.- Lec} 
XY. 7 \ ae Me 
Level 1 [A] [B] [Cc] 
- 
Root Level [non-overlaid portion of the task] 


Before analyzing transfers of control in this structure, however, it 
1s advisable to look at two possible extensions: 


@e The "CALLer must remain resident" rule, when applied to 
Subroutine nesting, implies that whenever we are executing 
within an overlay segment, all lower segments along the 
"path" from that segment to the root are also resident. For 
example, if executing in segment BBC, then BB, B, and of 
course the root are resident. There iS no reason not to 
allow a routine in segment BBC to CALL routines in BB, B, and 
the root - and CALL them directly, without vectoring. This 
is a "down-tree" CALL. 


Such "down-tree" CALLS are allowed, but are conditional. For 
instance, assume a BBC routine CALLS a BB routine. Before 
RETURNing to the BBC routine, the BB routine MUST NOT itself 
CALL “up-tree" (as it would normally be able to do had it not 
been CALLed from above). If the BB routine CALLed ae BBA 
routine, for example, the BBA routine could successfully 
RETURN to the BB routine, but when the BB- routine’ then 
RETURNed to the BBC routine it would find the BBA segment 
resident instead of the BBC segment. Since the program could 
not detect this, the program would quickly run into trouble. 


In other words, CALLing up-tree presents no problems, but 
when CALLing down-tree, watch out for nested up-tree 
excursions that would violate the "“"CALLer must remain 
resident" rule. 


e While it is reasonable to distribute autoload vectors’ into 
the overlay segments that actually use them, it is awkward to 
distribute segment descriptors in the same manner (e.g., with 
sharable and/or read-only PLAS~merped memory-resident 
libraries). Therefore, you should place all segment 
descriptors in the task root segment. Given their typical 
size and numbers, they should present no problems. 


Placing task root segments in the segment descriptor allows 
you to relax the requirement that up-tree CALLS go up just 
one tree level. You link the segment descriptors into an 
actual tree structure that mirrors the conceptual overlay 
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tree. Then you modify the autoload routine to load ALL 
segments on the path between the CALLer and the target. 
Thus, for example, when a "B" segment routine CALLS a "BBB" 
segment routine, the CALL is redirected to an autoload vector 
in the B segment that specifies the actual target virtual 
address plus the segment descriptor address of the BBB 
segment. The autoload routine then checks to see if BBB is 
resident and, if not, loads the BBB segment and works its way 
down the segment descriptor tree toward the root, loading 
additional segments as necessary. 


Under the assumption that a segment is resident only 1f all 
lower segments on the path between it and the root are also 
resident, this approach should achieve the desired result. 
However, to guarantee that assumption, the autoload routine 
must mark all segments that do not share the new path 
non-resident, even if some of them do not conflict with the 
virtual memory used by the new path. This ususally has 
little effect upon the overlay cache, since overlay 
configurations frequently conflict. Cases to the contrary 
can often be optimized through use of the co-tree structures 
discussed below. | 


The previous description of the basic code-overlaying mechanisms 
translate into the following: 


1. 


Any "node" (overlay segment) in the tree can "see" and CALL 
directly all routines in the same node and in any lower nodes 
that lie on the path between it and the root. 


Any node in the tree can "see" and CALL indirectly (through 
an autoload vector) all routines in nodes directly above it 
in the overlay tree. In our sample tree, a routine in node B 
could CALL routines in any node whose name begins with B - 
but no node whose name begins with A or C. A routine in the 
task root can clearly CALL routines in any node in the 
structure. 


Except as discussed in the first two items above, nodes 
cannot "see" (or CALL) each other. You may normally place 
routines with the same globally-defined entry point names in 
nodes that cannot see each other without conflict. However, 
if a reference to such a duplicated entry point is made by a 
lower node which can "see" both instances of it, TKB cannot 
determine which node should be used to satisfy the up-tree 
CALL and will generate a diagnostic message indicating the 
ambiguity. 
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4. Down-tree CALLS should always be carefully examined for 
nested up-tree CALLs that would displace the CALLer. 


5. Any use of overlays at task AST (asynchronous) level also 
runs arisk. The task-level overlay context could easily be 
changed “underneath" the running’ code. Isolating segments 
used at AST levei from those used at task level in separate 
co-trees is one possible way to avoid this. A few products 
such as RMS-1ll have special asynchronous versions’ with 
internal controls that allow mixed task/AST level operation, 
but most do not. 


Wherever a CALL is specified in the above list, a JMP would also be 
usable. 


B.1.2.2 Making the Tree More Flexible - The structure described above 
works well for applications that fall naturally into tree-structured 
organization of control flow. Though applications in many cases do 
lend themselves to such organization, and in many others can be made 
to comply with minimal changes, there are times when Strict 
tree-structuring imposes significant penalties in use of task virtual 
address space and/or task image size on disk due to excessive module 
duplication throughout the structure. 


One way to add flexibility to the available control flow mechanisms is 
to build some explicit extensions into selected portions of the code. 
For example, suppose that the FOO routine in node BBC of our _ sample 
tree would benefit from access to the copy of the BAR routine in node 
AB of the tree. We could legally just duplicate the BAR routine in 
node BBC (as long as the root does not CALL BAR, since duplicating BAR 

would then result in an ambiguous up-tree reference), but if BAR is 
very large this could be awkward. Instead, however, we could create 
the following "cross-tree" transfer mechanism: 


[FOO routine in node BBC] 


FOO:: : °° (Normal initial FOO code) 
JMP BARI] * (We would normally CALL BAR here) 
FOO2:: ; - (Remainder of the FOO code) 


[Special transfer routine in the root] 


BARI:: CALL BAR 
JMP FOO2 
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The result of this is that FOO legally JMPs to the BARI transfer 
routine (which must be low enough in the tree so that both FOO can see 
it and it can see BAR), BARI] legally CALLs BAR, BAR legally RETURNs to 
BARI, and BARI legally JMPs' back to the proper point in FOO. The 
stack depth has not been affected by this indirection. 


For high-level languages that do not permit coding such a_= sequence 
directly, one could add a second special MACRO-11 transfer module in 
the CALLing overlay segment that JMPs to BAR] and then RETURNS’) after 
the root module JMPs back to it, and CALL this second module from the 
high-level language code. Though such a linkage does not preserve 
stack depth, due to the added CALL, it will be suitable in many cases 
(e.g., routines that communicate using the "standard" PDP-11l_ R5 
CALLing sequence). 


While inelegant in some ways, the approach as described is a 
reasonable way to avoid excessive module duplication and reduce 
Virtual address space use by effectively allowing a CALLed routine to 
displace its CALLer. One must of course be willing to accept the 
performance overhead of loading the target (plus any non-resident 
lower nodes) on every CALL . and reloading the CALLer (plus any 
displaced lower nodes) on every RETURN, but for infrequent operations 
this may well be tolerable. One must also ensure that the target 
routine does not require access to any data (or code!) resident in the 
portion of the tree that is displaced when the target is loaded, but 
again for restricted use this may not be a difficult limitation. 
Finally, remember that the condition codes are not preserved through 
the RETURN to FOO in this case. 


B.1.2.3 Co-trees —- TKB makes another mechanism available for further 


control over use of the overlay cache area: the co-tree. 
Conceptually, co-trees allow division of the cache into independent 
segments that do not affect each other. In effect, they become 


multiple tree structures, each of which functions independently of the 
others. 


Since overlay activity in one tree does not affect the others, all 
nodes in each tree can "see" all entry points in all other trees just 
as if these entry points were in the root segment (though the CALLS 
must still be vectored through the autoload mechanism). Thus a CALL 
to a different co-tree is much like a "down-tree" CALL. In 
particular, you must ensure that any nested CALLS back to the 
originating tree's code do not change its overlay context such that 
the CALLer becomes non-resident (the RMS-11 user-provided "get-space" 
routine feature is an example of such a "CALL-back" situation that 
must be handled with care). 
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The Task Builder's normal processing of the default object module 
library (typically SYSLIB) is designed to avoid occurrences of such 
inter-co-tree CALL-back situations in cases where their existence 
would not be obvious due to the implicit nature of the references. 
The /FULL switch may be used - with caution - to override this 
behavior when necessary. 


Because each co-tree must reserve its full complement of virtual 
memory all the time, co-tree structures may be somewhat less efficient 
in use of virtual memory (though more efficient in use of disk space) 
than eguivalent-function single-tree structures with increased module 
duplication. The Task Builder Manual's descriptions and examples of 
overlaying provide insights into optimizations and trade-offs among 
virtual memory, task image size on disk, and performance for’. single- 
and multiple-tree structures, as does the RMS-1l "prototype" ODL file 
RMS11.ODL for specific cases involving the RMS-11 co-tree. 


B.1.2.4 Overlaying Data - At’ the beginning, we decided that 
intercepting data references would have required on-the-fly 
interpretation of the instruction stream with prohibitive performance 
and complexity cost. For this reason, all overlaying of data is left 
to the user to do correctly. 


TKB does, however, provide the tools for overlaying data. Data 
program sections (PSECTs) can be given the "local" attribute, in which 
case they will be placed in the overlay segment where the module 
containing them occurs. As long as such data is referred to only by 
the code in that segment (or, optionally, by code in segments directly 
above that segment in the tree structure), all should go well. If 
referred to by lower segments in the tree, or by segments in other 
trees, there is no guarantee that the correct data will be resident, 
and the user is responsible for avoiding such references. 


(Data may also occur in-line with code, though this is normally not 
considered good programming practice. Such data acts much the same as 
data in a "local" PSECT.) 


When a data PSECT is given the "global" attribute, on the other hand, 
TKB merges all contributions to that PSECT on a given path downward so 
that they in fact occur in the lowest segment on that path in _ which 
any contribution to that PSECT is made. Thus all segments that make 
contributions to that PSECT may freely refer to it in its entirety 
without the danger of up-tree data references. Note, however, that 
there is still no active protection against reference from lower in 
the tree. 
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A common programming error involves mixing local and global PSECTs 
that have the same name. Since the attributes differ, they are 
treated as different PSECTs, and the local portions are not merged 
with the global portions. 


TKB recognizes use of routine addresses as data just as it recognizes 
any up-tree CALL-type reference. In a CALL or JMP table, for example, 
an entry of the form .WORD FOO will be correctly resolved to an 
autoload vector when the routine is up-tree (or in another tree) from 
the reference to it. TKB has one unfortunate idiosyncracy in this 
area: when an up-tree module makes a contribution to a global data 
PSECT that is forced down-tree to the lowest node in which references 
to this PSECT occur, any autoload vectors associated with this 
contribution are placed in the up-tree module's segment rather than in 
the lower segment in which the reference actually winds up. Thus if a 
lower node refers to such a contribution, there is no guarantee that 
the required autoload vector will be resident, and the results can be 
both surprising and difficult to diagnose. Thankfully, such 
Situations seldom occur in normal use of the overlay facilities. 


Finally, TKB allows explicit loading of up-tree data segments via use 


of the .NAME directive and a "dummy" CALL. This can be useful when 
large amounts of data must be referred to under program control. 
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B.2 PDP-11l CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS 


The recent development of the cluster library facility reflects a 
long-term cooperative effort on the part of many DIGITAL PDP-11 
software groups. Library clustering retains the performance and 
ease-of-development advantages associated with use of memory-resident 
libraries, allows more flexible and efficient use of physical memory 
by RSX-11M-PLUS and RSTS/E operating systems, and competes favorably 
with disk overlay structures in use of task virtual memory. 


This discussion reviews and supplements the extensive description in 
the Task Builder Manual, which covers much of this material in 
slightly different, and sometimes more detailed, form. 


B.2.l1 Simple Task Structure and Memory Mapping 


The 16-bit byte-oriented architecture of the PDP-11l presents the user 
with 32 KW of addressable memory in the address range 0 to 177777 
(octal). In multiprogramming systems, the operating system uses’7 the 
memory management hardware to map this range of VIRTUAL addresses (as 
seen by the task) onto one or more ranges of PHYSICAL memory 
locations, and to ensure that the physical memory associated with each 
task is Suitably protected from unauthorized use by other tasks. This 
mapping is established through eight hardware Active Page Registers 
(APRs), each of which controls the mapping and protection of up to 4 
KW of task virtual address space, beginning on the appropriate 4 KW 
virtual address boundary. The APR specifies the start address in 
physical memory and the size of the task section (both in units of 
32-word blocks, the mapping granularity). 


The simplest structure is one in which task virtual memory maps onto a 
continuous series of physical memory locations, as illustrated in 
Figure B-l. As shown in the figure, the task does not require a _ full 
32 KW of physical memory, and APRs 5, 6, and 7 are set up to reflect 
the limits of the task memory envelope. Mapping need not be static. 
If the task is checkpointed to disk to give another task. an 
opportunity to use the physical memory, for example, it may on return 
occupy a different area in physical memory. If the task requests more 
space from the operating system, it will acquire access rights’ to 
additional physical memory. 


The physical memory associated with a task may, in fact, exceed 32 KW, 
under software control of the operating system. The virtual memory 
mapped under hardware control at any instant, however, can never 


exceed eight "pages," each a maximum of 4 KW in size, and each 
beginning on a 4 KW virtual address boundary. This ignores systems 
that support supervisor mode mapping and instruction/data space 
separation in user tasks - these extend addressable virtual memory 


through use of the additional APR sets available on PDP-11/70 and 
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PDP-11/44 processors. 


For large applications, 32 KW may be inadequate to contain all _ the 
necessary code and data for a task. The traditional solution is to 
overlay the task code. This breaks it up into segments, which are 
loaded on demand from disk and replaced with other segments when no 
longer needed. Such disk overlaying (which decreases task performance 
due to the extra disk I/O overhead) is performed under software 
control of the task's integral overlay run-time system. Overlay 
segments can be loaded at any word-aligned virtual address boundary. 


They do. not change the virtual-to-physical mapping of the task in any 
way. 
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Figure B-l: Simple Task Structure and Memory Mapping 
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B.2.2 Libraries and Virtual Address Windows 


Having eight APRs to work with, a task can map to as many as_ eight 
disjoint sections of physical memory (under operating system 
Supervision, of course). Intermediate software structures called a 
Virtual Address Windows in the system- controlled task header describe 
each such disjoint section. 


The example described in the previous section had the entire task 
contained in a Single continuous section of physical memory, and hence 
required only a single window (Window 0). As illustrated in Figure 
B-2, however, Task A has been linked to Library A, a memory-resident 
library. Since:‘there is no guarantee that the two will be loaded into 
adjacent sections of physical memory (or that they will have 
equivalent hardware protection requirements), two virtual address 
windows are needed. Window 0, as always, maps the task itself, using 
APRs 0 through 4; the task is permitted both read and write access to 
this section of memory. Window 1 maps the library using APRs 6 and 7; 
typical libraries will allow only read access by tasks. Since APR 5 
is not currently in use, the task could dynamically extend itself into 
this virtual address range (libraries are conventionally mapped in the 
highest available APRs to facilitate this), or could dynamically 
create an additional virtual address window to map APR 5 to some other 
portion of physical memory if space for a third window in the task 
header was specified when the task was built. 
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Figure B-2: Libraries and Virtual Address Windows 
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B.2.3 Library Sharing and Multiple Libraries 


Figure B-3 illustrates a more complex (and more typical) case, with 


multiple tasks and libraries resident in physical memory at the same 
time. 


Task A is still mapped to Library A as before. Task B is also mapped 
to the same physical copy of Library A. One of the benefits of uSing 
sharable re-entrant memory-resident libraries - rather than linking 
the library code into each task that uses it - is the saving in 
physical memory use that sharing allows. If the code were resident in 
the tasks, however, it might be possible to overlay it from disk. 
This would cut down on per-task physical memory requirements’ and 
increase the amount of virtual memory available for the rest of the 
code in the task (but also decrease performance due to the additional 
I/O to disk required for task execution). 


Whereas Task A maps Library A in APRS 6 and 7 (base virtual address 
140000), Task B maps Library A in APRs 4 and 5 (base virtual address 
100000). This can be done only if the code in the library is 
position-independent (PIC - descriptions of position-independent code 
and re-entrancy can be found in the PDP-11 Processor Handbook). The 
fact that both tasks use Window 1 to map the library is coincidental. 


Task B is also mapped to Library B. Two areas are worthy of note: 


1. It is fortunate that Task B is. small. The two libraries 
combined take up fully half the available virtual address 
space (by using four APRs between them). Task A is too large 
to be able to map to both libraries simultaneously. If their 
code were instead disk-overlaid within Task A, there might be 
room for it, though performance would suffer and the code for 
Library A would no longer be sharable. 


2. Whenever Task B is in memory, both libraries must also be in 
memory. A region is forced into physical memory whenever an 
in-memory task maps any portion of it, and Task B cannot run 
unless 25 KW of physical memory is available - a 9 KW block 
for the task itself, and an 8 KW block for each library. 
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Figure B-3: Library Sharing and Multiple Libraries 
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B.2.4 Library with Memory-Resident Overlays 


The RMS-11 V1.8 full-function memory-resident library RMSRES is an 
example of code which, for reasons of performance and sharability, is 
configured as a (re-entrant, position-independent) library but, for 
reasons of size (about 23 KW), cannot reasonably be mapped "flat-out" 
by tasks. The Task Builder allows such large libraries to _ be 
"resident-overlaid," using the Program Logical Address Space (PLAS) 
directives to map within the library region. The mapping operation is 
far less time-consuming than a disk overlay operation. With RMSRES, 
one APR is continually mapped to common support code in the Ilibrary 
"root," and a second APR is used to map whichever library "leaf" 
segment is currently in use (there are five of these). Even though 
the library is contained in a single region, the code is mapped in two 


often discontinuous pieces, therefore an additional window is required 
in the task. 


This approach consumes only 8 KW (two APRs) of the task'’s virtual 
address space, while giving the task the benefit of 23 KW of. 
(sharable) support code. This all happens with no disk overlay 
performance penalty - though disk-overlaid RMS can be contained in 
about 5 KW per task virtual/physical memory. Despite the fact that no 
more than 8 KW of the library is mapped by a single task at any one 
time, the entire library must be resident in physical memory when = any 


portion is mapped by a resident task, since regions cannot be loaded 
piecemeal. 


In Figure B-4, a single task is using both RMSRES (mapping to an 
arbitrary "leaf" segment is shown) and the 7 KW DIBOL memory-resident 
library - which is not PLAS-overlaid. Two points are worth noting: 


1. The two libraries again consume half the available task 
Virtual address space. Even though the DIBOL library is 
smaller than 8 KW, the fact that it exceeds 4 KW means’ that 
two APRs are needed to map it. While the physical memory 
required is 7 KW, the virtual memory impact on the task is 8 
KW. The "extra" 1 KW at the "top" of APR 5 is not available 
for use by the task. No other task window can be mapped to 
it, as it does not begin on an APR (4 KW) address boundary. 
Similar smaller unusable virtual address ranges can be found 
at the top of both of the APRs (6 and 7) used to map into 
RMSRES. The unused 1 KW at the top of APR 3, however, could 
be used by the task if necessary. It is continuous with the 
task region, and task Window 0 could be extended _ to include 
1 oe 


2. To run at all, the task requires 45 KW of physical memory (15 
KW for the task itself, 23 KW for RMSRES, and 7 KW for DIBOL, 
in continuous blocks). 
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Figure B-4: Library With Memory-Resident Overlays 
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B.2.5 Clustered Libraries 


As described in the previous section, multiple libraries are good for 
performance and potential sharing of physical memory, but not so good 
for task virtual address space, and minimum physical memory 
requirement (at least when only a single task is using the libraries). 
More flexibility is needed -—- and PDP-11l task structure provides it in 
the window mechanism. Windows are not statically associated with 
specific regions. They may be created and deleted as needed, at 
relatively low performance cost. In particular, when two libraries do 
not interact directly with one another (i.e., they do not need to _ be 
mapped simultaneously), they may alternately make use of the same task 


virtual address space (APR) range under control of the task's integral 
overlay run-time system. 


As Figure B-5 illustrates, this structure presents the same task 
configuration as discussed in the previous section. Now, however, RMS 
and DIBOL share the same two APRs (6 and 7). At the moment, DIBOL is 
mapped by the task, and RMS is not. Because of this, RMS need not 
occupy physical memory (unless some other resident task is mapped _ to 
RMSRES), and the instantaneous physical memory requirement for the 
running task drops from 45 KW to 22 KW. If an RMS request occurs, of 
course, RMSRES must be mapped. However, DIBOL must first be unmapped, 


and hence again the instantaneous physical memory requirement is 
reduced (38 KW vs. 45 KW). 


Thus, the task can run in as little as 38 KW of physical memory, 
though if there is less than 45 KW (appropriately distributed) RMSRES 
and DIBOL will "swap" against each other, resulting in disk I/O 
Similar to overlaying. The effect is to use the physical memory 
controlled by the operating system as a code cache. When the _ supply 
is plentiful, performance approaches the optimal multiple library 
case. When memory gets tight, performance degrades gradually as disk 
I/O activity relieves the pressure (and improves again dynamically 


when more physical memory becomes’ available). Additional libraries 
(such as an FMS library) may be added to the cluster as long as the 
rule that all are independent of each other is followed. In such a 


case, the minimum physical memory requirement is unaffected unless one 
of the libraries added is larger than the previous largest library in 
the cluster. 


RSX-1L1M-PLUS systems allow the most dynamic use of memory, as 
described above. RSTS/E systems tie libraries to specific areas in 
physical memory, but allow use of this physical memory for other 
purposes when it is not required by the library that "owns" it. 
RSX-11M systems do not support demand region loading, and hence do not 
experience any reduction in required physical memory. All libraries 
must always be resident. 


PDP-1ll CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS 


Also, the largest VIRTUAL address space requirement of any library in 
the cluster is all the user task sees. RMSRES, DAPRES (the library 
Supporting RMS remote access via DECNET), FMS, and DIBOL can, for 
example, all share the same 8 KW (two APRs) of task virtual address 


Space. This was, in fact, the original impetus for library 
clustering. The advantages in using physical memory were recognized 
later. 
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Figure B-5:; Clustered Libraries 
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B.2.6 Cluster Libraries - Implementation Detail 


The library clustering mechanism is implemented as an extension to 
existing Task Builder overlay structures. To the overlay run-time 
system, a library cluster resembles a null-rooted PLAS- overlaid 
co-tree, with each library a sub-tree. With the optional exception of 
the first library in the cluster, each of these sub- trees must itself 
have a null root. This structure simply aids the TKB in using its 

normal tree processing mechanisms to build the task structure. 


When the first library in the cluster has a non-null root segment, TKB 
builds the task such that the loader will load and map this library 
root when the task itself is loaded. Thereafter, the task-resident 
overlay run-time system keeps watch over the co-tree mapping. If a 
reference into the library cluster causes its APR mapping to change 
from one library (region) to another, the mapping context for the 
displaced library (region) is saved on the stack and is restored upon 
exit from the newly-called library. 


The first library in the cluster (assuming it has a non-null root) is 
always the initial library mapped. Therefore, any reference to 
another library in the cluster will always displace it, and it will 
always be re-mapped on exit. It is thus termed the "default" member 
of the cluster, for two reasons. First, mapping reverts to it when no 
Other library has a routine in progress, and second, references made 
to it normally do not require any "push-down" mapping context to be 
saved on the stack - since the reference will not normally displace 
one of the other libraries’ mapping. In other words, the default 
member of the cluster may usually be treated by the task just as if it 
were a non-clustered library. TKB takes advantage of this by 
Suppressing generation of overlay run-time system autoload vectors for 
references to the non-null root of the default cluster member. The 
four words per root entry point saved by such direct addressing can be 
Significant for default libraries with large numbers of entry points 
in the root - such as language OTS libraries. (If such libraries have 
PLAS-mapped “leaves" above the root, reference to entry points in the 
leaves will be autoload-vectored as usual). 


If all libraries in the cluster have null roots, the first library to 
be called by the task takes the role of the default member of the 
cluster. Once it has been mapped, any reference to another cluster 
member will displace it, and restore its mapping on exit. Since it 
(as well as the other libraries) has a null root, autoload vectors 
will be generated for ALL entry points referenced by the task. 


Note that this implementation does not require that all libraries in 
the cluster use the same number of APRs or the same number of virtual 
address windows. It does require, however, that they all be mapped, 
starting at the same task virtual address (APR boundary). This, in 
turn, means that all member libraries in a cluster must either be PIC, 
or built at the same virtual address. 


B-24 


B.2./ 


PDP-11l CLUSTER LIBRARIES AND THEIR USE IN APPLICATIONS 


Summary and Implications 


Understanding how cluster libraries work makes it easier to understand 
(and remember) how to design and use them properly. To summarize: 


Library clustering allows tasks to use the same virtual 
address space range (APRs) for multiple purposes (leaving a 
larger range of virtual address space free for other use), 
while retaining the ease-of-development and code-sharability 
features of normal memory-resident libraries. 


There are two costs associated with use of cluster libraries: 


1. The overlay run-time system and its data structures 
(several hundred words total) must be built into the root 
of your task. If your task already required the overlay 
run-time system for other reasons, the additional size 
increase is relatively small. 


2. A reference to a non-default member of the cluster causes 
mapping/re-mapping operations to occur. The typical 
overhead is 2-10 milliseconds per reference (far less 
than a typical disk I/O operation), depending on 
processor speed and the number of windows in the affected 
libraries. 


Library clustering allows RSX-11M-PLUS and RSTS/E operating 
systems to make more flexible use of physical memory, since a 
task maps only one library at a time. When memory is in 
short supply, a task may be able to run (albeit more slowly) 
which could not run at all if the libraries were not 
clustered. When a library is not mapped for long periods of 
time, the physical memory may be put to other use. 


Library clustering is not transparent to the libraries in the 
cluster. They must make no direct reference to each other 
(see below), and any which are not PIC must be built at _ the 
same starting virtual address. 


Library clustering is not fully transparent to the user task: 


dis 


The nature of the "push-down" mapping mechanism requires that 
any CALL into the cluster be of the form JSR PC,... (rather 
than, for example, JSR R5,...). While JMPs into the cluster 
are acceptable, co-routine linkages are unacceptable. 
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2. In general, the task must access the cluster only as 
described above. The task must not "remember" virtual 
addresses within the cluster, and cannot use the .NAME 
Facility to load library data tables. 


3. Since push-down mapping affects the stack depth, parameters 
may be passed on the stack across the task/cluster interface 
only if an argument pointer is used. 


The above three restrictions are relaxed only in the case of the 
default member of the cluster, and only then when it is known that no 
Other member is currently “pushed down" on the stack (see next 
section). 


B.2.8 Inter-Library References and Miscellaneous Points 


That completes this description of how clustering works and what its 
limitations are. One of the limitations clearly needs a work-around. 
For example, a language or FMS library needs access to the FCS or RMS 
library for file access, and to say that such combinations cannot be 
clustered is just not acceptable. | 


Any work-around is not a part of the clustering mechanism per se. Tt 
1s a cooperative effort on the part of the interacting libraries. FCS 
and RMS, for example, both provide linkage routines (modules FCSVEC 
and RORMSC, respectively) which must be built into any library whose 
code contains direct references to the FCS/RMS functions (e.g., 
OPENS/SOPEN). These special modules field any FCS/RMS request made 
within the library and pass it - using the low-core absolute linkage 
to the FCS or RMS task-resident impure area - to another FCS or RMS 
routine which exists in the task itself. This routine then calls into 
the FCS/RMS library, thus avoiding any direct inter-library call. (In 
the case of FCS, the "routine" is simply a JMP through an autoload 
vector.) 


Note, however, that the FCS/RMS global entry point symbols now appear 
in the calling library's symbol table. They will be visible to the 
user task, unless the calling library is built with .GBLXCL statements 
for each such symbol. Since it is not normally desirable to "vector" 
RMS references from the task through some intermediate library, the 
~-GBLXCL mechanism is generally appropriate. In the case of FCS, it is 
mandatory, as these same symbols are used as the entry points to the 
FCS library and will conflict if not suppressed. 


The mechanism described above is equally useful for  non-clustered 
libraries which need access to FCS-' or RMS without being bound to 
specific external routine entry points. This is independent of 
whether the FCS/ RMS code is task-resident or in a library of its own. 
An alternative approach is for the calling library to invoke a service 
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routine of its own in the task, which then dispatches to FCS/RMS 
directly. 


Finally, the calling library must contain nothing (data structures, 
file specification strings, etc.) that the FCS/RMS library needs to 
"see" in the execution of its duties. This is the caller's end of the 
bargain. RMS completion routines are called from the in-task RMS 
linkage code after exit from RMSRES, and hence may be present in the 
caller's library (which has by then been re-mapped). "Get space" 
(GSA) routines provided by the user are called with the RMS library 
mapped, but will execute correctly regardless of location provided the 
address given to RMS reflects an in-task autoload vector (the RMS 
Mapping will be "pushed down" if necessary to map the GSA routine, and 
will be restored transparently on GSA routine exit). 


This last situation reflects one of the potential pitfalls of 
"default" libraries. Tf such a library is clustered with RMS and 
provides a GSA routine address in its (non-null) root segment, when an 
RMS operation is performed, the call out of RMSRES to the GSA routine 
will, in fact, transfer control to some random location within the RMS 
library. This is because the default member is not mapped at the time 
and the overlay run-time system is not invoked on the reference (no 
autoload vector was generated). There are three possible remedies: 


1. Place the GSA routine in the task rather than in the library. 


2. Place the GSA routine in a PLAS-overlaid "leaf" of the 
default library - whose entry points are autoload-vectored. 


3. Build the first library as the other cluster members with a 
null root - which will force autoload vectoring throughout. 


A situation similar to the above applies to synchronous’ traps. Any 
trap service routine in the cluster must be suitably autoload-vectored 
through the controlling task, as the routine may not be mapped at the 
moment the trap occurs. At present, the overlay run-time system's 
handling of its data structures is not suited to any use of overlaying 
during asynchronous trap processing unless it is the only time 
overlaying occurs. An enhancement is under development, and when it 
appears, asynchronous trap servicing may be handled as described for 
synchronous trap servicing. 


B.2.9 WRITE Access to Clustered Libraries 


For P/OS V1.7, the overlay run-time system has been modified to allow 
write access to (non-"default") clustered libraries that have not been 
installed read-only. 
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Such libraries may be useful for the following purposes: 


Oo Passing information between cooperating application tasks 
(the tasks should provide their own access synchronization) 


O To extend the effective available read/write virtual memory 
usable for task impure data 


In both cases, the task(s) must ensure that the library is mapped by 
calling a routine in the library that does not RETURN to the caller 
until any access to the read/write data is completed. This is not 
normally necessary for a non-null-rooted ‘default’ cluster member, 
Since it is usually already mapped as desired. 


B.2.10 NULLIB 


The special non-null-rooted default cluster member NULLIB was provided 
in previous P/OS releases for two purposes: 


@® to guard against potential memory fragmentation problems that 
might cause task deadlock in certain instances. 


@® to provide better performance in cases when a null-rooted 
cluster member would otherwise become the ‘effective' default 
member of the cluster and would be re-mapped (and potentially 
re-loaded from disk) unnecessarily. Assuming that, 
typically, the application would access other cluster members 
than the first one accessed, re-mapping that first member 
after every access to some other one could prove costly. 


The increased physical memory now standard for P/OS makes the memory 
fragmentation problems considerably less likely for most applications. 
Also now that the RMSRES and POSSUM resident libraries are fixed in 
memory, there is no possibility of disk loading overhead when one of 
these becomes the effective default member of a cluster. 


As a general rule, when all members of a library cluster have null 
roots, the application should attempt to ensure that the first library 
accessed (which will become the effective default cluster member) is 
the one that the application will refer to most frequently. This will 
minimize the likelihood of unnecessary mapping and possible disk 
loading. 
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B.3 OPTIONS IN TASK ORGANIZATION 


The following examples have been chosen to demonstrate the options for 
organizing a task which needs to use the following P/OS services: 
RMS, Callable System Services (POSSUM), and User Interface Services 
(POSRES). 


® Option l: FLAT.TSK 
Completely flat task structure. All task modules are in a 


single segment. The three resident libraries are mapped in 
their own APRs. 


Advantages: Easiest taskbuild command file to construct. No 
special attention has to be made to placement of data. Less 
mapping activity necessary. 

Disadvantages: Most costly in terms of virtual memory space. 


® Option 2: CLUST.TSK 


Task region is a flat structure. The resident libraries are 
clustered against each other. 


Advantages: Because the resident libraries share APR 
mapping, other APRs are freed for task uSe. 


Disadvantages: More mapping and unmapping required by 
runtime services. 


@® Option 3: VECTOR.TSK 
Task space contains minimal code. Most code has_ been 
relocated to a user-written cluster library (USRRES). This 
library is clustered against RMSRES, POSSUM, and _ POSRES. 
Data required by USRRES must reside in task address space. 


Advantages: Even more address space available in task area. 


Disadvantages: More difficult to organize task code and 


data. A vectoring scheme must be implemented for library 
data references and subroutine calls from one library in the 
cluster to another. Extra mapping and unmapping by the 


overlay runtime system. 


® Option 4: OVERLAY .TSK 


Task itself is overlaid. All code and data which are needed 
to call RMSRES, POSSUM, and POSRES reside in one branch of 
the tree. Code not using these libraries is overlaid against 
code using libraries. 
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Advantages: Extends task virtual address space considerably 
because code/data for library references are removed from 
root segment of task and are consequently able to be 
unmapped. 


Disadvantages: More complicated .ODL file. Requires some 
knowledge of library-specific requirements. Requires logical 
separation of functionality. 


Implementation details follow. 
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B.3.1 FLAT.TSK 

This is the simplest structure to concoct. Ina flat task 
task control can be directly transferred to mainline code. 
Nevertheless, the example uses the control module ROOT in order to 
provide a basis for comparison with the alternative options. 


structure, 


B.3e-1.1 FLATBLD.CMD - 

; control mainline RMS,POSSUM 
: module code & POSRES 

: data 
FLAT, FLAT = ROOT, MAINLINE, ROOTDATA 

vA 

; each library will have its own apr assignment 
LIBR = POSRES:RO 

LIBR = RMSRES:RO 

LIBR = POSSUM:RO 

TASK = FLAT 


; define and assign logical units needed by this task: 
UNITS = 7 
ASG = SY¥:1:2:3:4:7 


ASG = TI:5 
GBLDEF = TRGTLN:1 !lun for target file (call to PROATR) 
GBLDEF = HLSLUN:2 !lun for help file (not used in this example) 
GBLDEF = MNSLUN:3 !lun for menu file 
GBLDEF = MSSLUN:4 !lun for message file (not used in this example 
GBLDEF = TTSLUN:5 !lun for POSRES services terminal I/O 
GBLDEF = WCSLUN:7 !lun for POSRES wildcard directory search 
GBLDEF = TTSEFN:2 levent flag for POSRES terminal I/O 
EXTSCT = FLSBUF: 2000 !provide a buffer for file specs (OLDFIL) 
EXTSCT = MMSBUF:2000 ‘buffer for multi-choice menu (OLDFIL) 
EXTSCT = MNSBUF:2000 !buffer for additional options menu (OLDFIL) 
Ty. 
B.3-1.2 ROOT.MAC - 

etitle coderoot 

eident /01.00/ 

-enabl LC 

emcall exitSs 


ies 
* The operational code for this test task is found in MAINLINE.MAC. 
; Necessary data structures are in ROOTDATA.MAC. 
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esbttl 

epsect 
START : 

MOV 

CALL 

EXITSS 


~sbttl 
~psect 
DATATBL: 
e WORD 
e WORD 
e WORD 
e WORD 
e WORD 


e END 
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Task root code 


#DATATBL, RO stable of subroutine parameter blocks 
MAINLN ;mainline task code 
>done 


Data table to drive mainline code 
roodat,d,rw,con 


OLFPAR 7call oldfil first 

‘FAB ;will need FAB addr to setup call to 
LUN 

FIDBUF sthree-word buffer for file id 
POSPAR spossum (proatr) parameter block) 
START 


B.3.1.3 MAINLINE.MAC - 


etitle 
eident 
-enabl 


emcall 
emcall 
emcall 
fhdofs 


ole 


Inputs: 


™=@ “=6 =6 =@=6@ =O@ WE We BB WS BWH WE VNH WH WH BWE BMH WH WS WO 


Mainline code 
701-007 
ic 


gqiowSs, alunSs 
Sparse, Ssearch, Scompare, S$fetch, $store 
Ehdof$ 
-define file header offsets for UC.CON 


Mainline code for test task. 

This module will: 
1. Establish proper lun assignments for terminal and target file. 
2. Call OLDFIL in POSRES to allow choice of target file. 
3. Call RMS to determine FILE-ID of .target file. 
4. Call PROATR in POSSUM to determine whether file is contiguous. 
5. Output result to screen. 


Most data for this module lives in ROOTDATA.MAC. This will permit thi 
module to be incorporated into a resident library which may cluster 
against RMSRES, POSSUM, and POSRES and to share data with that library 


There is some read-only data in this module which is included to 
demonstrate its possible use in a cluster library. 


RO -> Data table in the format: 
eword Oldfil parameter block 
~word address of rms FAB 
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; -word address of lun for target file 
; eword address of 3-word buffer for file id 
; eword address of parameter block for possum 
; Outputs: none 
~sbttl Mainline code 
-psect 
MAINLNs: : 
MOV (RO)+,R5 ;parameter block for oldfil 
MOV RO,-(SP) ;preserve input pointer across call 
MOV R5,-(SP) ;and also oldfil parameter block address 
CALL OLDFIL get a file spec 
MOV (SP)+,R5 ;restore oldfil parameter block 
MOV (SP)+,RO ;restore input table 
TST @2(R5) successful? 
BLE 10$ >no 
MOV (RO)+,R2 ;get fab address 
SSTORE @Q@8.(R5),FNS,R2 ;store size of filespec (from oldfil) 
MOV @(RO)+,R1 
SSTORE R1,LCH,R2 ;enter lun in FAB 
SPARSE R2 call RMS 
SCOMPARE #SUSSUC,STS,R2 *success? 
BNE 10S -no 
SSEARCH R2 eget file id into nam block 
SCOMPARE #SUSSUC,STS,R2 ;successful? 
BNE 10$ sno, error 
SFETCH R1,NAM,R2 *get NAM block address 
MOV (RO)+,R3 sbuffer to receive file id 
SFETCH O(R3),FID,R1 eretrieve File ID into buffer 
MOV (RO)+,R5 ;proatr parameter block address 
; The proatr parameter looks as follows: 
; eword 
; eword addr. of 8-word status block 
; -word addr. of request word 
; sword addr. of buffer to construct attribute list 
; eword addr. of file-id buffer 
: eword lun addr. 
MOV #0,@4(R5) :initialize request - get file attributes 
; by file id 
MOV 6(R5),RO ;:get address of attribute buffer 
> fill in attribute list: 
MOVB #3,(RO)+ sattribute type is file characteristics 
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MOVB #2,(RO)+ stwo words 
MOV RO, (RO) construct a buffer address 
ADD #4,(RO)+ ;point past attribute list 
CLR (RO)+ eend of attribute list 
CLR (RO) sinitialize cell to receive 
*characteristics 
; ~ BYTE S52 attribute type,size 
; e WORD 1s location of output 
; -»WORD 0 snull ends attribute list 
1$: .WORD 0 | ;returned value from proatr 
CALL PROATR sget attributes 
MOV 2(R5),R1 sstatus block address 
LST | 2(R1) success? 
BLE 10S >no, pass back error 
BIC #~C<UC.CON>,(RO) s:clear all but contiguous bit in 


es attribute word 

-if bit set, then file contiguous 

eif bit clr, then file not-contiguous 
; and (RO)=0 


;pick up address of messages 
> code must be pic since this will go into a /PI library 


MOV PC,R1 sassume contiguous 
ADD #CONTIG—-. ,R1 
MOV #CONTIZ,R2 
TST (RO) contiguous if non-zero 
BNE 5$ eyes, contiguous 
MOV PC,R1 snon-contiguous 
ADD #NOCONT-.,R1 
MOV #NOCONZ ,R2 
5S: 
ALUNSS #5,#"TI *point. terminal lun to the right place 
CLR -(SP) create io status block 
CLR -(SP) 
MOV SP,R3 spoint to it 
QIOWSssS #TO.WVB,#5,#1,,R3,,/<R1,R2,#40> ;entertain 
MOV (SP)+,(SP)+ *clear off iosb 
10S: 
RETURN 
esbttl Miscellaneous data 
»psect misdat,d,ro 
contig: eascii <33>/[23/<33>/[10;10H/ 
ascii /The file you have chosen is contiguous/ 
contiz = .-contig 


OPTIONS IN TASK ORGANIZATION 


nocont: eascii <33>/[273/<33>/[10;10H/ 

eascii /The file you have chosen is not contiguous/ 
noconz = .-nocont 

.even 

-end 


B.3.1.4 ROOTDATA.MAC - 


Piaf bass Ge ba 3) DATA FOR TASK ROOT 
~ident /01.00/ 

~enabl i Ke. 

emcall fabSb, nam$b, poolSb 


“ 


This module contains data needed by resident libraries (and in some 


cases in-task root). Data must be mapped when resident library is 
called. 


= 6 


=S@ SE B=E@ BS 


~psect roodat,d,rw,con 

eOBTIL DATA FOR OLDFIL 
prompt: eascii /Step right up! See if file is contiguous/ 
promz = .-~prompt 

.even 
prompz: ~word promz s;indirect reference for oldfil 


OLEpar: s 


eword olfpaz *-Size of parameter block 

eword olfsts Status block address 

eword numcho snumber of choices 

-word fna efile name string 

-word ofsiz sarray (1 element) for filespec size( 
~word nowild sno wildcard default 

eword nosiz sno length for no wildcard default 
-word prompt etext 

-word prompz 

eword nomsg -no message 

eword nosiz 

eword nomsg 

eword nosiz 


olfpaz = <.-olfpar>/2 - 1 


olfsts: oblkw 2 Status block 

numcho: eword 1 sone choice only 

ofsiz: ~blkw 1 ewill contain size of filespec 
nowild: *no wildcard 

nomsg: sno message 
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nosizZ: 


~SBTTL 
luns:: 


fidbuf:: 


e~SBTTL 
pospar:: 
~word 
eword 
word 
~word 
~word 
eword 
stablk: 
bufl: 
buf2: 
eSBTTL 
fna: .blkb 
dna: .ascii 
dns = .-dna 
| eeven 
dnasiz: 
rss = 
rsa: .blkb 
ess = 
esa: .blkb 
even 
fab:: 
£Snam 
fSfna 
fSdna 
£Sdns 
fabSe 
nam: namS$b 
nSesa 
nSess 
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~word 0 


“no size 


DATA FOR RMS CALLS 


eword 


~blkw 3 


trgtin 


DATA FOR POSSUM CALL 


5 
stablk 
bufl 
buf2 
fidbuf 
lun 


~blkw 8. 
eword 0 
~oblkw Se 


eaddr. 
addr. 
esaddr. 
saddr. 
eaddr. 


of 
OF 
of 
of 
of 


starget lun 


8-word status block 


request word 


buffer to construct call 
buffer containing file-id 


lun for file 


;request word 


-enough for an attribute 


RMS DATA STRUCTURES 


256% 


J/SY:3:0/ 


»word 


22% 
rss 


255. 
ess 


fabSb 
nam 
fna 
dna 
dns 


esa 
ess 


dns 


sebuffer for file specification 


*look for the latest version on default vol 


force even boundary 


eindirect reference for oldfil 


resultant string 


-expanded string 


snam block address 


sfile specification 
default file spec. 


edna size 


addr. 


expanded string address 
;size of esa buffer 
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n$rsa rsa sresultant string address 
n$rss rss size of rsa buffer 

namSe 

poolSb 

pSfiab 1 sone fab 

psSbuf DL2% ;one-block buffer 

p$bdb 1 sone buffer descriptor block 
poolSe 

end 
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B.3.2 CLUST.TSK 


This task makes use of the cluster library facility to free some APRs 
which would otherwise be used to map to resident libraries. The task 
itself is still a flat structure. Because the cluster library 
facility uses the overlay runtime system the task incorporates an 
overlay descriptor file. The .ODL file describes this flat structure 
in a manner similar to the specification of modules in the previous 
example (FLAT.TSK). 


Only one member of a library cluster may have a non-null root. ot 
there is a library which meets this description, it must be the 
default library of the cluster (appear first in the CLSTR- option 
line). Mapping to this default library is always restored after the 
completion of a call to another member of the cluster. Normally a 
higher-level language OTS falls into this category. 


In the case in which there is no library with a non-null root, the 
library which is INVOKED first becomes the default library de facto, 
regardless of its position in the CLSTR option line. The consequence 
of this is that if the task makes repeated calls to a particular 
library, it would be advantageous to make a call to the most often 
invoked library before calling any less frequently used library. 


CLUST, CLUST = CLUST/MP 


CLSTR = RMSRES,POSRES , POSSUM: RO 


TASK = CLUST 


UNITS = 7 

ASG = SY:1:2:3:43:7 
ASG = TI:5 

GBLDEF = TRGTLN:1 
GBLDEF = HLSLUN:2 
GBLDEF = MNSLUN3:3 
GBLDEF = MSSLUN:4 
GBLDEF = TTSEFN:2 
GBLDEF = TTSLUN:5 
GBLDEF = WCSLUN:7 
EXTSCT = FLSBUF:2000 
EXTSCT = MNSBUF:2000 
—* = MMSBUF:2000 
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B.3.2.-2 CLUST.ODL - 
; control 
. module 
» ROOT ROOT- OTHER- RMSROT 
° Mainline RMS,POSSUM 
; code & POSRES 
° data 
OTHER: ~FCTR MAINLINE- ROOTDATA 


* include RMS root modules (RMSROT) so that POSRES routines 
° can call RMS (see discussion of USRRES, below) 
@LB: [1,5] RMSRLX 


e END 
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B.3.3  VECTOR.TSK and USRRES.TSK 
This example demonstrates 


1. How to remove code from task space and place it in a resident 
library. 


2. How to build a resident library with a null root so that’ the 
library may be used as part of a cluster of resident 
libraries. 


3. How to address data in the task root from the resident 
library. | 


4, How to provide a facility to call other members of the 
cluster from the user-written cluster library. 


In this example, the user-written library is intended to be installed 
read-only and the library cluster mapped RO. As a result, there 
cannot be any read/write data in the library; there is, however, some 
read-only data in this library for demonstration purposes. 


Note 


In the following discussion, the terms "task space", 
"task root", and "task" all refer to a task which maps 
to the resident library USRRES. 


e3e3e-l1 USRRESBLD.CMD - 
Build a PIC 
resident library 
Include .STB 
file for 
tasks which 
map to this 


e@ =e =e ~e ~6 ~e se we (GD 


library 
USRRES/-HD/PI/LI, USRRES, USRRES = USRRES/MP 
PAR = USRRES:0:0 
STACK = 0 
; Insure that the symbol table for this library will contain 
; references to the externally available entry point(s): 
GBLREF = MAINLN 
; Force the task builder to check that the root vectoring module 
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is included in the task using this library for cross-cluster calls 
and accessing data in the root. 


BLINC = YANKME 


This library calls POSRES and POSSUM services (OLDFIL and 

PROATR, respectively). The entry point names must be resolved 

when building this library, but cannot be included in the library 
~-STB, Since references to these symbols from the task must be 
resolved by the library which contains the routine. (See discussion 
of cross-cluster calls.) 
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GBLXCL 


= PROATR 
GBLXCL = OLDFIL 
/ 7 
B.3.3.2 USRRES.ODL - Resident Library - The following .ODL file 


describes the resident library. It is a non-overlaid resident library 
with a null root. Any module without code or data allocation will 
suffice as a root; SYSLIB includes the module NULL for this purpose. 


e ROOT LB: {1,1]SYSLIB/LB:NULL- ! (CODE) 
CODE: sE CTR *MAINLINE- RESVEC- SYSLIB/LB:RORMSC:RMSSYM 


e END 


B.3.3.3 Discussion —- The module MAINLINE is’ declared autoloadable, 
indicating to the task builder to mark its global entry point(s) 
appropriately in the symbol table of USRRES. Calls to these routines 
from the task will generate autoload vectors. The autoload indicator 
is used in conjunction with the GBLREF option in the taskbuild command 
file. The GBLREF option instructs the taskbuilder to place the symbol 
in the .STB file for this library. This permits the calling task to 
have access to that entry point. 


The modules RORMSC and RMSSYM from SYSLIB permit this resident library 
to call RMSRES, which may be clustered against USRRES. This is 
accomplished by vectoring these calls through the task root. The 
vectoring module RESVEC illustrates the use of this scheme for those 
components which do not already provide a similar facility (see 
below). 
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Vectoring is required for two purposes: 
1. Accessing data in the task root from the library. 
2. Cross-cluster calls. 


Since the library must be taskbuilt before the referencing task, the 
library cannot reference the task directly. The task may pass data 
addresses, for example, as parameters to library routines. 
Alternatively, the library may address task space via a limited number 
of fixed addresses which remain meanings from task to task. This area 
is referred to as the "low-core" context of the task image. 


As part of the low-core context, the taskbuilder automatically 
deposits the address of the first word of the psect $SVEX1 in the 
location SVEXT. Since SVEXT is always at the same address in all 
tasks, a library may use this location to find the beginning of the 
SSVEX1 psect, whose actual virtual location will undoubtedly vary from 
task to task. 


Negative offsets from the beginning of the S$SVEX1 PSECT are reserved 


for Digital impure area vectors. Users may employ any positive 
offset; however, care should be taken to guarantee that other 
applications (e.g. high-level languages) are not already using the 


locations in $SVEX1. 
The psect has the following attributes: 
»-PSECT SSVEX1,D,GBL,REL,OVR 


The OVR attribute allows contributions to the PSECT to come from 
different sources while maintaining a fixed point of reference from 
the beginning of the PSECT. A SYSLIB module contains a global symbol 
pointing to the beginning of this PSECT. The address of this symbol 
is deposited by the taskbuilder in the location SVEXT. 


Therefore a library routine may execute the following instruction to 
point Rn to the beginning of SSVEX1. 


MOV @#SVEXT,Rn 


Rn is any one of the general purpose Registers. The absolute 
addressing mode (@ ) is required to guarantee position independence of 
the library. 


The library routine RESVEC makes use of the fact that a task built 
against this library will contain impure area vectors required by 
USRRES. The resident library can insure that the vector-declaring. 
module is included in the task by using the GBLINC option; this option 
results in an error ina task built against this library if the 
specified symbol is not resolved. 
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A module in USRRES callS PROATR by a normal JSR, PC: 


CALL PROATR 


A module must be included in the resident library to vector this call 
through the task root. 


03.3.4 Excerpt from RESVEC.MAC - 

This global symbol must be excluded from the .STB of USRRES. 
Otherwise, the taskbuilder would not be able to resolve the symbol 
unambiguously between USRRES and POSSUM. The GBLXCL option in the 
USRRES taskbuild command line instructs the taskbuilder to exclude 
the symbol. 

ROATRs: : 
This code is written in this manner so as to preserve all registers. 
MOV @#SVEXT,-(SP) ;get pointer to SSVEX1 psect 

; (SP) address of MYVECT (see below) 

;point to table 

; (SP) addr of INDIRECT 

;PROATR transfer point is second in table 
; (SP) addr. of 2nd word in table 
Cc 


=o HU ~e ~e ~e ~e se to 


MOV @(SP)+,-(SP) 
ADD #2,(SP) 

MOV @(SP)+,-(SP) get contents of 2nd word of table 

(SP) addr. of "PROATR" 

In actuality, the stack contains the address of an overlay runtime 
autoload vector. 

JMP @(SP)+ stransfer to "PROATR" (overlay runtime 

;system) 


~e@ we 


At this point, the task is executing in the overlay runtime system, 
which will save the mapping context of USRRES, remap to POSSUM, and 
transfer control to PROATR. At the conclusion of PROATR, the overlay 
runtime system will restore mapping to USRRES and return control to 
the instruction following the call to PROATR. 


A similar procedure would be followed to address the data space in the 
task root. Here a register is available. 


MOV @Q@#SVEXT ,RO saddress of MYVECT 

MOV (RO) ,RO ‘point to INDIRECT (vector table) 

MOV 4(RO),RO scontents of entry is address of data 
> table 


B.3.3.5 VECTOR.MAC (Root vector module) - 
; Define symbol required by USRRES 
YANKME == 0 


»~PSECT SSVEX1,D,GBL,REL,OVR 
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* This label will be equivalent to the value which the taskbuilder has 
; deposited in SVEXT because the psect SSVEX1 is OVR (overlaid). 
MYVECT : 
; It is good practice to add a level of indirection. This will insure 
; that this use of this particular psect will consume only a single 
; word. 

eWORD INDIRECT 

ePSECT JMPTBL,D,RO,CON 
INDIRECT : 

eWORD OLDFIL seused in cross-cluster calls 

eWORD PROATR sused in cross-cluster calls 

~WORD PNTDAT sused to point to data in task root 

e~PSECT IMPURE,D,RW,CON 
PNTDAT : 

~-BLKB 120. eread/write data area 

«END 
> Command file to build task which maps to user-written resident 


CLSTR 
TASK 


UNITS 
ASG 
ASG 
GBLDEF 
GBLDEF 
GBLDEF 
GBLDEF 
GBLDEF 
GBLDEF 
GBLDEF 


EXTSCT 
EXTSCT 
EXTSCT 
es 


cluster library 
VECTOR, VECTOR 


VECTOR 


5 


VECTOR/MP 


RMSRES , POSRES , POSSUM ,USRRES : RO 


SY¥:1:2:3:4:7 


es 


5 

TRGTLN:1 
HLSLUN: 2 
MNSLUN:3 
MSSLUN:4 
TTSEFN:2 
TTSLUN:5 
WCSLUN:7 


FLSBUF:2 


000 


MNSBUF: 2000 


MMSBUF: 2 


000 
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B.3.3./7 VECTOR.ODL i= 
eROOT ROOT- OTHER- RMSROT 


task root 
vectoring 
: module 
OTHER: ~-FCTR ROOTDATA- VECTOR 


6 =G6 BE 


@LB: [1,5] RMSRLX 


«END 


ott 
a 
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B.3.4 OVERLAY.TSK 


This example shows that a program can separate functionality in such a 
way that the data required by a resident clustered library need not 
always be mapped. 


In order to achieve this goal, one must first carefully analyze the 
potential for functional independence of routines. The example is 
structured to demonstrate a group of routines which call services in 
RMSRES, POSSUM, and POSRES anda second group of routines which do 
some computation and QIO's to the terminal. 


The second stage in the process is to determine which modules’ are 
required by the resident library in question, and then force the 
taskbuilder (through the .ODL file) to place these modules in the 
appropriate branch of the overlay tree structure. If the modules were 
not specified by the .ODL file, they would be in the task root rather 
than in a branch and therefore would consume shared virtual address 
Space and be mapped even when not needed. 


added calls (to COMPUTE and WTRES) 
eROOT ROOT2- (LEFT, RIGHT) 


>; The root module has changed from previous examples because of the 


> The module CLLWTR is included to call WTRES (wait for resume 

>; key) in POSRES. The module COMPUTE displays a message to press 
> <RESUME> when the user is ready to continue. In order to keep 

* all references to POSRES in the "left" branch of the tree, the 

> .ODL forces the root to transfer control up-tree in order to 

>; call POSRES. 

LEFT: ~FCTR *MAINLINE- *CLLWTR- ROOTDATA- BUFS- RMSROT- LIB 
* Force other syslib references into this branch 

LIB: .FCTR LB:[1,5]SYSLIB/DL 


> These are the buffers required by POSRES services in this example 
BUFS: -FCTR SYSLIB/LB:PTIMP:PTFLF:FLFAB:PTDUM 


RIGHT: ~-FCTR *COMPUTE- SYSLIB/LB:EDTMG 
@LB: [1,5] RMSRLX 


e END 
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B.3.4.2 


OVERLABLD.CMD - 


OVERLAY, OVERLAY = OVERLAY/MP 


CLSTR = RMSRES,POSRES,POSSUM:RO 


TASK = OVERLY 


UNITS = 7 

ASG = SY:1:2:3:4:7 
ASG = TI:5 

GBLDEF = TRGTLN:1 
GBLDEF = HLSLUN:2 
GBLDEF = MNSLUN:3 
GBLDEF = MSSLUN:4 
GBLDEF = TTSEFN:2 
GBLDEF = TTSLUN:5 
GBLDEF = WCSLUN:7 
EXTSCT = FLSBUF:2000 
EXTSCT = MNSBUF:2000 
EXTSCT = MMSBUF:2000 
// 

B.3.4.3 ROOT2.MAC - 


eTITLE ROOT2 
eident /01.00/ 


-enabl lc 
emcall exitSs 


~- 


(Section B.3.1.3). 


(Section B.3.1.4). 


=e 26 BE BE BE WS 


®@ @~G WE 


eOBTTL TASK ROOT CODE 


epsect 

START : 
MOV #DATATBL,RO 
CALL MAINLN 


CALL COMPUTE 


CALL CLLWTR 


The alternate mapping is COMPUTE.MAC. 
is in the same module. 


The operational code for this test task is found in MAINLINE.MAC 


Necessary data structures are in ROOTDATA.MAC. 


All data for that segment 


stable of subroutine parameter blocks 
smainline task code -— "LEFT" 


do something else - "RIGHT" 
wait for the resume key - "LEFT" 


, 
°° do the waiting in the posres services 
> branch of the tree 
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MOV #DATATBL,RO ;jJust for fun, call first operation again 
CALL MAINLN : 
EXITSS edone 


eSOBTTL DATA TABLE TO DRIVE MAINLINE CODE 
epsect roodat,d,rw,con 


DATATBL: 
eWORD OLFPAR call oldfil first 
eWORD FAB ;will need FAB address to set up call to rms 
eWORD LUN 
eWORD FIDBUF s>three-word buffer for file id 
~-WORD POSPAR spossum (proatr) parameter block) 


» END START 


B.3.4.4 CLLWTR.MAC — 
eTITLE CLLWTR - CALL WTRES FROM OVERLAY 
ident /01.00/ 


+ | 
This module will call the POSRES service WTRES (Wait for Resume key). 
It is placed in an overlay branch in order to segregate all posres 
calls from the root and/or other branches, i.e. to localize virtual 
address requirements for calling posres services. 


™G@ BS BS WS a @ ~= 6 


CLLWTR:: 
CALL WIRES 
RETURN 


e END 


B.3.4.5 COMPUTE .MAC = 
eLITLE COMPUTE 
-ident /01.00/ 


eenabl lc 
-mcall qiowSs, mrkt$s, wtseSs 


i 


This module will consume space and time. The overlay branch which 
shares this virtual address space will do more interesting things, 
e.g. call RMS, POSSUM, and POSRES. 

After this module does its thing, it will instruct the observer to 
press the resume key. Since all calls to POSRES are in the other 
branch, this will return to ROOT2 to allow the root to transfer 
control to the POSRES-calling overlay. 


=@ ™=@ =B =P BE WS ™G BE WH 
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MRKEF = 3 ;event flag to mark time 
~psect 
COMPUTEs:: 
MRKTSS #MRKEF,#2,#2 ;:mark time for 2 seconds 
MOV #DATBUF , RO ;address of data buffer 
MOV #DATBUZ,R1 ;Ssize in words 
MOV #1,R2 ;£i111 buffer with miscellaneous garbage 
1S: 
MOV R2,(RO)+ -enter first word 
INC R2 ;bump data 
SOB Risso 
23% 
MOV #DATBUF,RO snow add it up 
MOV #DATBUZ ,R1 
CLR R2 ;double precision 
CLR R3 
3$:2 
ADD (RO)+,R3 
ADC R2 
SOB R135 
4S: 
MOV R2,DPHIGH ;copy to memory 
MOV R3,DPLOW 
oe 
MOV #OUTBUF ,RO ;set up for Sedmsg 
MOV #FORMAT,RI sinput string 
MOV #ARGBLK ,R2 eargument block 
CALL SEDMSG sformat output 
10S: 
WISESS #MRKEF slet user read previous message 
155-2 
QIOWSS #I0O.WVB,#5,#1,,#I10OSB, ,<#OUTBUF,R1,#40> ;:print new one 
20S: 
RETURN 
-SOBTTL DATA FOR THIS BORING ROUTINE 
epsect boring,d,rw 
DATBUZ = 100. esa hundred bottles of beer on the wall 
DATBUF : eBLKW DATBUZ 
; KEEP THESE TWO VALUES TOGETHER, IN THIS ORDER: 
DPHIGHs: eWORD 0 
DPLOW: eWORD 0O 
OUTBUF * -BLKB 200. buffer for output message 
eNLIST BEX 
FORMAT : eASCII <33>/[20/<33>/[10:10H/ ;clear screen and locate curso 
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e-ASCII /This is the total: %T. Whoopee!/ 
-ASCIZ /Press <RESUME> to continue./ 


EVEN 
~LIST BEX 
ARGBLK: eWORD DPHIGH 
eWORD 0 
ITOSB: ~BLKW 2 
e END 


hoy 
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APPENDIX C 


FILES-11 ON-DISK STRUCTURE SPECIFICATION 


This appendix provides a specification of the on-media structure that 
is used by Files-ll. Files-1ll is a general purpose file structure 
which is intended to be the standard file structure for all medium to 
large PDP-11l systems. Small systems such as RT-1ll have been 
specifically excluded because the complexity of Files-ll would impose 
too great a burden on their simplicity and small size. 


This document describes structure level 1 of Files-ll, also called 
ODS-1 (on-disk structure version 1). This has been implemented on 
P/OS and on VMS. This document describes the final level of 
Functionality £Or ODS-1. Structure level 2 (ODS-2) has_ been 
implemented on VMS and is the basis for all new disk structure 
enhancements. 


C.l MEDIUM 


Files-ll is a structure which is imposed on a _ medium. That medium 
must have certain properties, which are described in the following 
section. Generally speaking, block addressable storage devices’ such 
as disks and Dectape are suitable for Files-ll. Therefore, Files-ll 
structured media are generically disks. 


C.1.1 Volume 


The basic medium that carries a Files-ll structure is a volume (also 
often called a unit), and is defined as an ordered set of logical 
blocks. A logical block is an array of 512 8-bit bytes. The logical 
blocks in a volume are consecutively numbered from 0 to n-l, where the 
volume contains n logical blocks. The number assigned to a _ logical 
block is called its logical block number, or__LBN. Files-ll is 
theoretically capable of describing volumes up to 232 blocks in size. 
In practice, a volume should be at least 100 blocks in size to be 
useful. Current implementations of Files-11l will handle volumes up to 
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224 blocks. 


The logical blocks of a volume must be randomly addressable. The 
volume must also allow transfers of any length up to 65k bytes, in 
multiples of four bytes. When a transfer is longer than 512 bytes, 
consecutively numbered logical blocks are transfered until the byte 
count is satisfied. In other words, the volume can be viewed as a 
partitioned array of bytes. It must allow reads and writes of arrays 
of any length less than 65k bytes, provided that they start on a 
logical block boundary and that the length is a multiple of four 
bytes. When only part of a block is written, the contents of the 
remainder of that logical block will be undefined. 


C.1.2 Volume Sets 


ODS-1 does not support volume sets. A volume set is a collection of 
related units that are normally treated as one logical device in the 
usual operating system concept. Each unit contains its own Files-ll 
structure. However, files on the various units in a volume set may be 
referenced with a relative volume number, which uniquely determines 
which unit in the set the file is located on. Other sections in this 
specification will make occasional reference to volume sets-~ and 
relative volume numbers’ where hooks for their implementation exist. 
Since volume sets have not been implemented as yet, however, no 
complete specification is provided here. 


C.2 FILES 


Any data in a volume or volume set that is of any interest (i.e., all 
blocks not available for allocation) is contained ina file. A file 
is an ordered set of virtual blocks, where a virtual block is an array 
of 512 8 bit bytes. The virtual blocks of a file are consecutively 
numbered from 1 to n, where n blocks have been allocated to the file. 
The number assigned to a virtual block is called (obviously) its 
virtual block number, or VBN. Each virtual block is mapped to a 
unique logical block in the volume set by Files-11l. Virtual blocks 
may be processed in the same manner as logical blocks. Any array of 
bytes less than 65k in length may be read or written, provided that 
the transfer starts on a virtual block boundary and that its length is 
a multiple of four. 


C.2.1 File ID 


Each file in a volume set is uniquely identified by a File ID. A File 
ID iS a )binary value consisting of 48 bits (3 PDP-11 words). It is 
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Supplied by the file system when the file is created, and must be 


supplied by the user whenever he wishes to reference a particular 
file. 


The three words of the File ID are used as follows: 
@ Word 1 - File Number 


Locates the file within a particular unit of the volume set. 
File numbers must lie in the range 1 through 65535. The set 
of file numbers on aunit is moderately (but not totally) 


dense. At any instant in time, a file number uniquely 
identifies one file within that unit. 


@ Word 2 - File Sequence Number 


Identifies the current use of an individual file number on a 


unit. File numbers are re-used. When a file is deleted its 
file number becomes available for future use for some other 
file. Each time a file number is re-used, a different file 


sequence number is assigned to distinguish the uses of that 
file mumber. The file sequence number is essential since it 
is perfectly legal for users to remember and attempt to use a 
File ID long after that file has been deleted. 


@ Word 3 - Relative Volume Number 


Identifies which unit of a volume set the file is located on. 
Volume sets are at present not implemented. The only legal 
value for the relative volume number in any context is zero. 


C.2.2 File Header 


Each file on a Files-1ll volume is described by a file header. The 
file header is a block that contains all the information necessary to 
access the file. It is not part of the file. It is contained in the 
volume's index file. (The index file is described in Section C.4.1l. 
The header block is organized into four areas, of which the first 
three are variable in size. 


C.2.2.1 Header Area - The information in the header area permits’ the 
file system to verify that this block is in fact a file header and, in 
particular, is the header being sought by the user. It contains’ the 
file number and file sequence number of the file, as well as its 
ownership and protection codes. This area also contains offsets to 
the other areas of the file header, thus defining their size. 
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Finally, the header area contains a user attribute area, which may be 
used by the user to store a limited amount of data describing the 
file. 


C.2.2.2 Ident Area - The ident area of a file header contains 
identification and accounting data about the file. Stored here are 
the primary name of the file, its creation date and time, revision 
count, date, and time, and expiration date. 


C.2.2.3 Map Area - The map area describes the mapping of virtual 
blocks of the file to the logical blocks of the volume. The mapping 
data consists of a list of retrieval pointers. Each retrieval pointer 
describes one logically contiguous segment of the file. The map area 
also contains the linkage to the next extension header of the file, if 
such exists. 


C.2.2.4 End Checksum - The last two bytes of the file header’ contain 
a 16 bit additive checksum of the remaining 255 words of the file 
header. The checksum is used to help verify that the block is in fact 
a file header. 


C.2.3 Extension Headers 


Since the file header is of fixed size, it is inevitable that for some 
files the mapping information will not fit in the allocated space. A 
file with a large amount of mapping data is therefore represented with 
a chain of file headers. Fach header maps a consecutive set of 

virtual blocks. The extension linkage in the map area links’ the 
headers together in order of ascending virtual block numbers. 


Multiple headers are also needed for files that span units in a volume 
set. A header may only map logical blocks located on its unit. 
Therefore, a multi-volume file is represented by headers on all units 
that contain portions of that file. 


C.2.4 File Header -—- Detailed Description 


This section describes in detail the items contained in the file 
header. Each item is identified by a symbol which represents the 
offset address of that item within its area in the file header. Any 
item may be located in the file header by locating the area to which 
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it belongs and then adding the value of its offset address. Users who 
concern themselves with the contents of file headers are strongly 
urged to use the offset symbols. The symbols may be defined in 
assembly language programs by calling and invoking the macro FHDOFS, 
which may be found in the macro library of any system that supports 
Files-ll. Alternatively, one may find the macro in the file 
FIIMAC.MAC, which may be obtained from the author. 


C.2.4.1 Header Area Description - The header area of the file header 
always starts at byte 0. It contains the basic information needed for 
checking the validity of accesses to the file. 


H.IDOF: 1 Byte - Ident Area Offset 


This byte contains the number of 16 bit words between the 
start of the file header and the start of the ident area. 
It defines the location of the ident area and the size of 
the header area. 


H.MPOF: 1 Byte - Map Area Offset 


This byte contains the number of 16 bit words between the 
Start of the file header and the start of the map area. [It 
defines the location of the map area and, together with 
H.IDOF, the size of the ident area. 


H.FNUM: 2 Bytes - File Number 

This word contains the file number of the file. 
H.FSEQ: 2 Bytes - File Sequence Number 

This word contains the file sequence number of the file. 
H.FLEV: 2 Bytes - File Structure Level 


The file structure level is used to identify different 
versions of Files-ll as they affect the structure of the 
file header. This permits upwards compatibility of file 
structures as Files-ll evolves, in that the structure level 
word identifies the version of Files-ll that created this 
particular file. This document describes version 1 of 
Files-ll. The only legal contents for H.FLEV is 401 octal. 


H.FOWN: 2 Bytes - File Owner UIC 


H.PROG H.FOWN+0 Programmer (Member) Number 


H.PROJ H.FOWN+1 Project (Group) Number 
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This word contains the binary user identification code (UIC) 
of the owner of the file. The file owner is usually (but 
not necessarily) the creator of the file. 


H.FPRO: 2 Bytes - File Protection Code 


This word controls what access all users in the system may 
have to the file. Accessors of a file are categorized 
according to the relationship between the UIC of the 
accessor and the UIC of the owner of the file. Each 
category is controlled by a four bit field in the protection 
word. The category of the accessor is selected as follows: 


e System - Bits 0 - 3 


The accessor is subject to system protection if the 
project number of the UIC under which he is running is 
10 octal or less. 


@® Owner - Bits 4 - 7 


The accessor is subject to owner protection if the UIC 
under which he is running exactly matches the file owner 
ULC. 


@e Group - Bits 8 - ll 


The accessor is subject to group protection if the 
project number of his UIC matches the project number of 
the file owner UIC. 


e World - Bits 12 - 15 


The accessor is subject to world protection if he does 
not fit into any of the above categories. 


Four types of access intents are defined in Files-ll: 
read, write, extend, and delete. Each four bit field in 
the protection word is bit encoded to permit or deny any 
combination of the four types of access to that category 
of accessors. Setting a bit denies that type of access 


to that category. The bits are defined as follows 
(these values apply to ae right-justified protection 
field): 


FP.RDV Deny read access FP.WRV Deny write access 
FP.EXT Deny extend access FP.DEL Deny delete access 


When a user attempts to access a file, protection checks 
are performed in all the categories to which he is 
eligible, in the order system - owner - group -- world. 
The user iS granted access to the file if any of the 
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H.FCHA: 2 Bytes - File Characteristics 


H.UCHA = 
H.SCHA = 


H.FCHA+O User Controlled Char. 
H.FCHA+1l System Controlled Char. 


him access. 


The user controlled characteristics byte contains 
following flag bits: 


UC.RCK 


UC.WCK 


UC.CNB 


UC.DLK 


UC.CON 


1 Bit, Reserved. 


Set if incremental dump (backup) is to 
be disabled for this file. 


Set if the file is to be write-back 


cached. For example, if a cache is used for 


the file data, data written by a user is 
only written back to the disk when is it 
removed from the cache. Clear for 
write-through cache operation. 


Set if the file is to be read-checked. 
All read operations on the file, 
including reads of the file header(s), 
will be performed with a read, 
read-compare to assure data integrity. 


Set if the file is to be write-checked. 
All write operations on the file, 
including modifications of the file 
header(s), will be performed with a 
write, read-compare to assure data 
integrity. 


Set if the file is allocated contiguous 
best effort. In other words, as contiguous 
possible. 


Set if the file is deaccess-locked. 
This bit is used as a flag warning that 
the file was not properly closed and may 
contain inconsistent data. Access to 
the file is denied if this bit is set. 


Set if the file is logically contiguous. 


For example, if for all virtual blocks in the 


file, virtual block i maps to logical 
block k+i on one unit for some constant 
k. This bit may be implicitly set or 
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cleared by file system operations that 
allocate space to the file. The user 
may only clear it explicitly. 


The system controlled characteristics byte contains’ the 
following flag bits: 


_ 3 Bits, Reserved. 
~ Reserved (Access Control List). 


SC.SPL Set if the file is an intermediate file 
for spooling. 


SC.DIR Set if the file is a directory. 


SC.BAD Set if there is a bad data block in the 
file. This bit is as yet unimplemented. 
It is intended for dynamic bad block 
handling. 


SC.MDL Set if the file is marked for delete. 
If this bit is set, further accesses to 
the file are denied, and the file will 
be physically deleted when no users are 
accessing it. 


H.UFAT: 32 Bytes - User Attribute Area 


This area is intended for the storage of a limited quantity 
of “user file attributes", i1.e., any data the user deems 
useful for processing the file that is not part of the file 
itself. An example of the use of the user attribute area is 
presented in Section C.5.1 (FCS File Attributes). 


S.HDHD: 46 Bytes - Size of Header Area 


This symbol represents the total size of the header area 
containing all of the above entries. 


C.2.4.2 Ident Area Description - The ident area of the file header 
begins at the word indicated by H.IDOF. It contains identification 
and accounting data about the file. 


I.FNAM: 6 Bytes - File Name 


FILES 


These three words contain the name of the file, packed three 
Radix-50 characters to the word. This name usually, but not 
necessarily, corresponds to the name of the file's primary 
directory entry. 


I.FTYP: 2 Bytes - File Type 


This word contains the type of the file in the form of three 
Radix-50 characters. 


I.FVER: 2 Bytes - Version Number 


This word contains the version number of the file in binary 
form. 


I.RVNO: 2 Bytes - Revision Number 


This word contains the revision count of the file. The 
revision count is the number of times the file has been 
accessed for write. 


I.RVDT: 7 Bytes - Revision Date 


The revision date is the date on which the file was last 
deaccessed after being accessed for write. It is stored in 
ASCII in the form "DDMMMYY", where DD is two digits 
representing the day of the month, MMM is three characters 
representing the month, and YY is the last two digits of the 
year. 


I.RVTI: 6 Bytes - Revision Time 


The revision time is the time of day on which the file was 
last deaccessed after being accessed for write. It is 
stored in ASCII in the format "HHMMSS", where HH 1s_ the 
hour, MM is the minute, and SS is the second. 


I.CRDT: 7 Bytes - Creation Date 


These seven bytes contain the date on which the file was 
created. The format is the same as that of the revision 
date above. 


I.CRTI: 6 Bytes - Creation Time 
These six bytes contain the time of day at which the file 
was created. The format is the same as that of the revision 


time above. 


I.EXDT: 7 Bytes - Expiration Date 
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These seven bytes contain the date on which the file becomes 
eligible to be deleted. The format is the same as that of 
the revision and creation dates above. 


- : 1 Byte - (unused) 


This unused byte is present to round up the size if the 
ident area to a word boundary. 


S.IDHD: 46 Bytes - Size of Ident Area 


This symbol represents the size of the ident area containing 
all of the above entries. 


Map Area Description 


The map area of the file header starts at the word indicated 
by H.MPOF. It contains the information necessary to map the 
virtual blocks of the file to the logical blocks of the 
volume. 


M.ESON: 1 Byte -—- Extension Segment Number 


This byte contains the value n, where this header is’ the 
n+lth header of the file. In other words, headers of a file 
are numbered sequentially starting with 0. 


M.ERVN: 1 Byte - Extension Relative Volume No. 


This byte contains the relative volume number of the unit in 
the volume set that contains the next sequential extension 
header for this file. If there is no extension header, or 
if the extension header is located on the same unit as this 
header, this byte contains 0. 


M.EFNU: 2 Bytes - Extension File Number 
This word contains the file number of the next sequential 
extension header for this file. If there is no extension 
header, this word contains 0. 

M.EFSQ: 2 Bytes - Extension File Sequence Number 
This word contains the file sequence numbér of the next 
sequential extension header for this file. If there is no 


extension header, this word contains QO. 


M.CTSZ: 1 Byte - Block Count Field Size 
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This byte contains a count of the number of bytes used to 
represent the count field in the retrieval pointers in the 


map area. The retrieval pointer format is described under 
M.RTRV below. 


M.LBSZ: 1 Byte - LBN Field Size 


This byte contains a count of the number of bytes used _ to 
represent the logical block number field in the retrieval 
pointers in the map area. The contents of M.CTSZ and M.LBSZ 
must add up to an even number. 


M.USE: 1 Byte - Map Words In Use 


This byte contains a count of the number of words in the map 
area that are presently occupied by retrieval pointers. 


M.MAX: 1 Byte - Map Words Available 


This byte contains the total number of words available for 
retrieval pointers in the map area. 


M.RTRV: variable -—- Retrieval Pointers 


This area contains the retrieval pointers that actually map 
the virtual blocks of the file to the logical blocks of the 
volume. Each retrieval pointer describes a consecutively 
numbered group of logical blocks which is part of the file. 
The count field contains the binary value n to represent a 
group of n+l logical blocks. The logical block number field 
contains the logical block number of the first logical block 
in the group. Thus each retrieval pointer maps virtual 
blocks j through j+n into logical blocks k through ktn, 
respectively, where j is the total number plus one of 
virtual blocks represented by all preceding retrieval 
pointers in this and all preceding headers of the file, n is 
the value contained in the count field, and k is the value 
contained in the logical block number field. 


Although the data in the map area provides for arbitrarily 
extensible retrieval pointer formats, Files-1ll has defined 
only three. Of these, only the first is currently 
implemented. The other two are presented out of historical 
interest. They will never be supported. 


Format l: M.CTSZ = l 
M.LBSZ = 3 


The total retrieval pointer length is 


four bytes. Byte 1 contains the high 
order bits of the 24 bit LBN. Byte 2 
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This symbol represents the size of the map 


Format 


Format 
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contains the count field, and bytes 3 
and 4 contain the low 16 bits of the 
LBN. 


22 MeCisZ = 22 
M.LBSZ = 2 


The total retrieval pointer length is 
four bytes. The first word contains a 


16 bit count field and the second word 
contains a 16 bit LBN field. 


3%. MsCTSZ = 2 
M.LBSZ = 4 


The total retrieval pointer length is 


six bytes. The first word contains a 16 
bit count field and the second and third 


words contain a 32 bit LBN field. 


10 Bytes - Size of Map Area 


area, 


including the space used for the retrieval pointers. 


not 
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C.2.4.3 End Checksum Description - The header check sum occupies’ the 
last two bytes of the file header. It is verified every time a header 
is read, and is recomputed every time a header is written. 


H.CKSM: 2 Bytes - Block Checksum 
This word is a simple additive checksum of all other words 


in the block. It is computed by the following PDP-11 
routine or its equivalent: 


MOV Header-address,R0O 
CLE Rl 
MOV +2 90D ep RZ 
10S: ADD (RO)+,R1 
SOB R2,10$8 
MOV R1,(RO) 


C.2.4.4 File Header Layout - 
Header Area 


H.MPOF Map Area Offset Ident Area Offset H. IDOF 
File Number H.FNUM 

File Sequence Number H.FSEQO 

File Structure Level H.FLEV 

a --------- = -- = $$$ $= $= = = = - == -- H.FOWN 

H .PROJ File Owner UIC H.PROG 
File Protection H.FPRO 

----------------~--- | ------------------- H.FCHA 

H.SCHA System Char. User Char. H.UCHA 
H.UFAT 


User Attribute Area 


meee S .HDHD 


Ident Area 
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File Name 
File Type 
Version Number 
Revision Number 
Revision Date 
I.RVTI 
-= Revision Time 
I.CRDT 
Creation Date 
Creation Time 
Expiration Date 
(not used) 
Map Area 


I.FNAM 
I.FTYP 
I.FVER 
I .RVNO 
I .RVDT 
jee Os 22 We 
L<BXDT 
------- S.IDHD 
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M.ERVN | Extension RVN | Ext. Seg. Num. | M.ESON 

Extension File Number M.EFNU 

Extension File Seq. Num. M.EFSQ 

M. LBSZ LBN Field Size Count Field Size M.CTSZ 
M.MAX Map Words Avail. Map Words in Use M.USE 

moan = ---------- | ------------------- S.MPHD 

M.RTRV 


Retrieval Pointers 


File Header Checksum H.CKSM 


C.3 DIRECTORIES 


Files-1l provides directories to allow the organization of files in a 
meaningful way. While the File ID is sufficient to locate a file 
uniquely on a volume set, it is hardly mnemonic. Directories are 


files whose sole function is to associate file name strings with File 
ID's. 


C.3.1 Directory Heirarchies 


Since directories are files with no special attributes, directories 
may list files that are in turn directories. Thus the user may 
construct directory heirarchies of arbitrary depth and complexity to 
structure his files as he pleases. 


C.3.1.1 User File Directories - Current implementations of Files-ll 
all support a two level directory heirarchy which is tied in with the 
user identification mechanism of the operating system. Each UIC is 
associated with a user file directory (UFD). References to files that 
do not specify a directory are generally defaulted to the UFD 
associated with the user's UIC. All UFD's are listed in the volume'’s 
MFD under a file name constructed from the UIC. A ULC. o£  -[n;m} 
associates with a directory name of "nnnmmm.DIR;1", where nnn and mmm 
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are n and m padded out to three digits each with leading zeroes. Note 
that all number conversions are done in octal. 


Two points should be noted here. The UFD structure described here is 
not intrinsically part of the Files-1]l on-disk structure. It is a 
convenient cataloging system applied by various operating systems. 
Also, there is no hard and fast relationship between the owner UIC of 
a file and the UFD in which it is listed. Generally, they will 
correspond, but not necessarily. 


C.3.2 Directory Structure 


A directory is a file consisting of 16 byte records. It is structured 
as an FCS fixed length record file, with no carriage control 
attributes (see Section C.5 for a description of FCS files). Each 
record is a directory entry. The entries are not required to be 
ordered, or densely packed, nor do they have any other relationship to 
each other, except that no two entries in one directory may contain 
the same name, type, and version. Each entry contains the following: 


File ID The three word binary File ID of the file that 
this directory entry represents. If the file 
number portion of the File ID field is zero, then 
this record is empty and may be used for a new 
directory entry. 


Name The name of the file may be up to 9 characters. 
Tt is stored as three words, each containing three 
Radix-50 packed characters. 


Type The type of the file (also historically referred 
EG as the extension) may be up to. three 
characters. It is stored as one word of Radix-50 
packed characters. 


Version The version number of the file is stored in binary 
in one word. 


Name 
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C.3.3 Directory Protection 


Since directories are files with no special characteristics, they may 
be accessed like all other files, and are subject to the same 
protection mechanism. However, implementations of Files-1ll support 
three special functions for the management of directories, namely 
FIND, REMOVE, and ENTER. A user performing such a directory operation 


must have the following privileges to be allowed the various 
functions: 


Find: READ 
Remove : READ, WRITE 
Enters: READ, WRITE 


Note that the same privilege is required for both enter and remove. 
The recovery for an operation that involves a remove at the beginning 
of the sequence is an enter. 


C.4 KNOWN FILES 


Clearly any file system must maintain some data structure on_ the 
medium which is used to control the file organization. In Files-ll 
this data is kept in five files. These files are created when a new 
volume is initialized. They are unique in that their File ID's are 
known constants. These five files have the following uses: 


File ID 1,1,0 is the index file. The index file is the root of the 
entire Files-ll structure. It contains the volume's bootstrap block 
and the home block, which is used to identify the volume and _ locate 
the rest of the file structure. The index file also contains all of 
the file headers for the volume, and a bitmap to control the 
allocation of file headers. 


File ID 2,2,0 is the storage bitmap file. It is used to control the 
allocation of logical blocks on the volume. 


KNOWN FILES 


File ID 3,3,0 is the bad block file. It is a file containing all of 
the known bad blocks on the volume. 


File ID 4,4,0 is the volume master file directory (or MFD). It forms 
the root of the volume’s directory structure. The MFD lists the five 
known files, all first level user directories, and whatever other 
files the user chooses to enter. 


File ID 5,5,0 is the system core image file. Its use iS operating 
system dependent. Its basic purpose is to provide a file of known 
File ID for the use of the operating system. 


C.4.1 Index File 


The index file is File ID 1,1,0. It is listed in the MFD as 
INDEXF.SYS;1. The index file is the root of the Files-1ll structure in 
that it provides the means for identification and initial access to a. 
Files-ll volume, and contains the access data for all files on the 
volume (including itself). 


C.4.1.1 Bootstrap Block - Virtual block 1 of the index file is the 
volume’s boot block. It is always mapped to logical block 0 of the 
volume. If the volume is the system device of an operating system, 
the boot block contains an operating system dependent program which 
reads the operating system into memory when the boot block is read and 
executed by a machine's hardware bootstrap. If the volume is not a 
system device, the boot block contains a small program that outputs a 
message on the system console to inform the operator to that effect. 


C.4.1.2 Home Block - Virtual block 2 of the index file is the 
volume's home block. The logical block containing the home block is 
the first good block on the volume out of the sequence 1, 256, 512, 
768, 1024, L280). eax 2567 The purpose of the home block is to 
identify the volume as Files-ll, establish the specific identity of 
the volume, and serve as the ground zero entry point into the volume’s 
file structure. The home block is recognized as a home block by the 
presence of checksums in known places and by the presence of 
predictable values in certain locations. 


Items contained in the home block are identified by symbolic offsets 
in the same manner as items in the file header. The symbols may be 
defined in assembly language programs by calling and invoking the 
macro HMBOF$, which may be found in the macro library of any system 
that supports Files-ll. Alternatively, one may find the macro in the 
file Fl1IMAC.MAC, which is available from the author. 
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H.IBSZ: 2 Bytes - Index File Bitmap Size 


This 16 bit word contains the number of blocks that make up 
the index file bitmap. (The index file bitmap is discussed 


in Section C.4.1.3. This value must be non-zero for a valid 
home block. 


H.IBLB: 4 Bytes - Index File Bitmap LBN 


This double word contains the starting logical block address 
Of the index file bitmap. Once the home block of a volume 
has been found, it is this value that provides access to the 
rest of the index file and to the volume. The LBN is stored 
with the high order in the first 16 bits, followed by the 
low order portion. This value must be non-zero for a valid 
home block. 


H.FMAX: 2 Bytes - Maximum Number of Files 


This word contains the maximum number of files that may be 


present on the volume at any time. This value must be 
non-zero for a valid home block. 


H.SBCL: 2 Bytes - Storage Bitmap Cluster Factor 


This word contains the cluster factor used in the storage 
bitmap file. The cluster factor is the number of blocks 
represented by each bit in the storage bitmap. Volume 
clustering can not be implemented in ODS-1. The only legal 
value for this item is l. 


H.DVTY: 2 Bytes - Disk Device Type 


This word is an index identifying the type of disk that 


contains this volume. It is currently not used and always 
contains 0. 


H.VLEV: 2 Bytes - Volume Structure Level 


This word identifies the volume's structure level. Like the 
file structure level, this word identifies the version of 
Files-l11 which created this volume and permits upwards 
compatibility of media as Files-ll evolves. The volume 
structure level is affected by all portions of the Files-1ll 
Structure except the contents of the file header. This 
document describes Files-ll version l. The only legal 
values for the structure level are 401 and 402 octal. The 
former (401) is the standard value for most volumes. The 
latter (402) is an advisory that the volume contains a 
multiheader index file. (A multiheader index file is 
required to support more than about 26,000 files. The index 
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file may in fact be multiheader without the volume having a 
structure level of 402). 


H.VNAM: 12 Bytes - Volume Name 


This area contains the volume label as an ASCII string. Tt 
is padded out to 12 bytes with nulls. The volume label is 
used to identify individual volumes. 


4 Bytes - Not Used 


H.VOWN: 2 Bytes - Volume Owner UIC 


This word contains the binary UIC of the owner of the 
volume. The format is the same as that of the file owner 
UIC stored in the file header. 


H.VPRO: 2 Bytes - Volume Protection Code 


This word contains the protection code for the entire 
volume. Its contents are coded in the same manner as the 
file protection code stored in the file header, and it is 
interpreted in the same way in conjunction with the volume 
owner UIC. All operations on all files on the volume must 
pass both the volume and the file protection check to be 
permitted. (Refer to the discussion on file protection 
described earlier under H.FPRO. 


H.VCHA: 2 Bytes - Volume Characteristics 


This word contains bits which provide additional control 
over access to the volume. The following bits are defined: 


@ CH.NDC - Obsolete, used by RSX-l1ID/IAS. Set if device 
control functions are not permitted on this volume. 
Device control functions are those which can threaten 
the integrity of the volume, such as direct reading and 
writing of logical blocks, etc. 


@e CH.NAT - Obsolete, used by RSX-11D/IAS. Set if the 
volume may not be attached, i.e., reserved for the sole 
use by one task. 


@ CH.SDI - Set if the volume contains only aé_e single 
directory. If this bit 


is set, no directories should be created on the volume 
other than the MFD. The access methods should also be 
informed of this situation, e.g. by setting the DV.SDI 
bit in the device characteristics word. 
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DFPR: 2 Bytes - Default File Protection 


This word contains the file protection that will be assigned 
to all files created on this volume if no file protection is 
specified by the user. 


: 6 Bytes - Not Used 
WISZ: 1 Byte - Default Window Size 


This byte contains the number of retrieval pointers’ that 
will be used for the "window" (in core file access data) 
when files are accessed on the volume, if not otherwise 
specified by the accessor. 


FIEX: 1 Byte - Default File Extend 


This byte contains the number of blocks that will be 
allocated to a file when a user extends the file and asks 
for the system default value for allocation. 


LRUC: 1 Byte - Directory Pre-access Limit 


This byte contains a count of the number of directories to 
be stored in the file system's directory access cache. More 
generally, it is an estimate of the number of concurrent 
users of the volume and its use may be generalized in the 
future. 


REVD: 7 Bytes - Date of Last Home Block 
Revision 
This ill defined field is in the standard ASCII date format 
and reflects the date of the last modifications to fields in 
the home block. 

REVC: 2 Bytes - Count of Home Block Revisions 


This field reflects’ the number of above mentioned 
modifications. 


: 2 Bytes - Not Used 

CHK1: 2 Bytes - First Checksum 
This word is an additive checksum of all entries preceding 
in the home block (i.e., all those listed above). It 1s 


computed by the same sort of algorithm as the file header 
checksum (see H.CKSM). 


KNOWN FILES 


H.VDAT: 14 Bytes - Volume Creation Date This area contains’ the 
date and time that the volume was initialized. It is in the 
format "DDMMMYYHHMMSS", followed followed by a single null. 
(The same format is used in the ident area of the file 
header, Section C.2.4.2. 


382 Bytes Not Used 


This area is reserved for the relative volume table for 
volume sets. This field will not be used, although some 
versions of DSC referenced this area. 


H.PKSR: 4 Bytes - Pack Serial Number 


This area contains the manufacturer supplied serial number 
for the physical volume. For last track devices, the pack 
serial number is contained on the volume in the manufacturer 
data. For other devices the user must supply this 
information manually. The serial number is contained in the 
home block for convenience and consistency. This field is 
part of the area defined by STD 167. / 


- : 12 Bytes - Not Used 


This field is reserved for the volume set name. This’ field 
is part of the area defined by STD 16/7. 


H.INDN: 12 Bytes - Volume Name 


This area contains another copy of the ASCII volume label. 
It is padded out to 12 bytes with spaces. It is placed here 
in accordance with the volume identification standard (STD 
167). 


H.INDO: 12 Bytes - Volume Owner 


This area contains an ASCII expansion of the volume owner 
UIC in the form "[{proj,prog]". Both numbers are expressed 
in decimal and are padded to three digits with leading 

zeroes. The area is padded out to 12 bytes with trailing 
Spaces. It is placed here in accordance with the volume 
identification standard (STD 167). 


H.INDF: 12 Bytes - Format Type 


This field contains the ASCII string "DECFILE11A" padded out 
to 12 bytes with spaces. It identifies the volume as being 


of Files-1ll format. It is placed here in accordance with 
the volume identification standard (STD 167). 


- : 2 Bytes - Not Used 


KNOWN FILES 


H.CHK2: 2 Bytes - Second Checksum 


This word is the last word of the home block. It contains 
an additive checksum of the preceding 255 words of the home 


block, computed according to the algorithm listed under 
H.CKSM. 


Home Block Layout 


Index File Bitmap Size H.IBSZ 
Index File H.IBLB 
Bitmap LBN 
Maximum Number of Files H.FMAX 
Storage Bitmap Cluster Factor H.SBCL 
Disk Device Type H.DVTY 
| Volume Structure Level H.VLEV 
| H.VNAM 
Volume Name 
oom (not used) om 
Volume Owner UIC H.VOWN 
Volume Protection H.VPRO 
Volume Characteristics H.VCHA 
Default File Protection H.DFPR 
(not used) 
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H.FIEX Def. File Extend Def. Window Size H.WISZ 
H.REVD Directory Limit Hise bRUC 


Volume Modification Date 
Volume Modification Count H.REVC 
(not used) 
First Checksum H.CHKI 
H.VDAT 
Volume Creation Date 
(not used) 
H.PKSR 
— Pack Serial Number 


KNOWN FILES 


; (not used) ; 
— _— a 
ae oe 
Format Type 


H.INDN 


H.INDO 


H.INDF 


H.CHK2 


KNOWN FILES 


C.4.1.3 Index File Bitmap - The index file bitmap is used to. control 
the allocation index file bitmap of file numbers (and hence file 
headers). It is simply a bit string of length n, where n is the 
maximum number of files permitted on the volume (contained in offset 
H.FMAX in the home block). The bitmap spans over as many blocks as is 
necessary to hold it, i.e., max number of files divided by 4096 and 
rounded up. The number of blocks in the bitmap is contained in offset 
H.IBSZ of the home block. 


The bits in the index file bitmap are numbered sequentially from 0 to 
n-l in the obvious manner, i.e., from right to left in each byte, and 
in order of increasing byte address. Bit j} is used to represent file 
number j+l: if the bit is 1, then that file number is in use. If the 
bit is 0O, then that file number is not in use and may be assigned to a 
newly created file. 


The index file bitmap starts at virtual block 3 of the index file and 
continues through VBN 2+m, where m is the number of blocks in the 
bitmap. It is located at the logical block indicated by offset H.IBLB 
in the home block. | 


C.4.1.4 File Headers - The rest of the index file contains all the 
file headers for the volume. The first 16 file headers (for file 
numbers 1 to 16) are logically contiguous with the index file bitmap 
to facilitate their location. The rest may be allocated wherever the 
file system sees fit. Thus the first 16 file headers may be _ located 
from data in the home block (H.IBSZ and H.IBLB) while the rest must be 
located through the mapping data in the index file header. The file 
header for file number n is located at virtual block 2+mtn (where m is 
the number of blocks in the index file bitmap). 


C.4.2 Storage Bitmap File 


The storage bitmap file is File ID 2,2,0. It is listed in the MFD as 
BITMAP.SYS;l. The storage bitmap is used to control the available 
Space on a unit. It consists of a storage control block which 
contains summary information about the unit, and the bitmap itself 
which lists the availablilty of individual blocks. 


C.4.2.1 Storage Control Block - Virtual block 1 of the storage bitmap 
1s the storage control block. It contains summary information 
intended to optimize allocation of space on the unit. The storage 
control block has the following format for disks with less than 
4096126, (516,096 blocks): | 
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(3 bytes) Not used (zero) 

(1 byte) Number of storage bitmap blocks (less than 127) 
(2 bytes) Number of free blocks in lst bitmap block 

(2 bytes) Free block pointer in lst bitmap block 

(2 bytes) Number of free blocks in nth bitmap block 

(2 bytes) Free block pointer in nth bitmap block 

(4 bytes) Size of the unit in logical blocks 


For larger disks the following format is used: 


(3 bytes) Not used (zero) 
(1 byte) Number of storage bitmap blocks (greater than 126) 
(4 bytes) Size of the unit in logical blocks 


(246 bytes) Not used (zero) 


NOTE 


Current implementations of Files-1ll do not correctly 
initialize the word pairs containing number of free 
blocks and free block pointer for each bitmap. block, 
nor are these values maintained as space is allocated 
and freed on the unit. They are therefore best looked 
upon aS 2n garbage words and should not be used by 
future implementations of Files-1ll until the disk 
structure is formally updated. 


C.4.2.2 Storage Bitmap - Virtual blocks 2 through n+l are the storage 
bitmap itself. It is best viewed as a bit string of length m, 
numbered from 0 to m-l, where m is the total number of logical blocks 
on the unit rounded up to the next multiple of 4096. The bits are 
addressed in the uSual manner (packed right to left in sequentially 
numbered bytes). Since each virtual block holds 4096 bits, n blocks, 
where n = m/4096, are used to hold the bitmap. Bit j} of the bitmap 
represents logical block j of the volume. If the bit is set, the 
block is free. If clear, the block is allocated. Clearly the last k 
bits ot the bitmap are always clear, where k is the difference between 
the true size of the volume and m, the length of the bitmap. 


The. size of the bitmap is limited to 256 blocks. in fact, due to 
existing implementations on all RSX systems, the retrieval pointers 
must be in one of the following two forms: 
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1. A single retrieval pointer mapping the entire BITMAP.SYS 
file. 


2. Two retrieval pointers, the first mapping the storage control 
block only, and the second mapping the entire bitmap proper. 


This restriction limits ODS-1 to a volume of 4096255 blocks 
(1,044,480 blocks or about 500 megabytes). 


C.4.3 Bad Block File 


The bad block file is File ID 3,3,0. It is listed in the MFD as 
BADBLK.SYS;1. The bad block file is simply a file containing all of 
the known bad blocks on the volume. 


C.4.3.1 Bad Block Descriptor - Virtual block 1 of the bad block file 
is the bad block descriptor for the volume. It is always located on 
the last good block of the volume. This block may contain a listing 
of the bad blocks on the volume produced by a bad block scan program 
or diagnostic. The format of the bad block data is identical to the 
map area of a file header, except that the first four entries (M.ESON, 
M.ERVN, M.EFNU, and M.EFSQ) are not present. The last word of the 
block contains the usual additive checksum. (See earlier in this 
chapter for a description of the map area.) This block is included in 
the bad block file to save the data it contains for future 
re-initialization of the volume. 


Bad Block Descriptor Layout 


Retrieval Pointers 


KNOWN FILES 


C.4.4 Master File Directory 


The master file directory is File ID 4,4,0. It is listed in the MFD 
(itself) as O0O0000.DIR;1. The MFD is the root of the volume's 
directory structure. It lists the five known files, plus whatever the 
user chooses to enter. In the two level UFD structure described in 
Section C.3.1.1, the MFD contains entries for all user file 
directories. 


C.4.5 Core Image File 


The core image file is File ID 5,5,0. It is listed in the MFD as 
CORIMG.SYS;1. Its use is operating system dependent. In general, it 
provides a file of known File ID for the use of the operating system, 


for use aS a swap area, for example, or as a monitor overlay area, 
eLcs 


C.5 FCS FILE STRUCTURE 


File Control Services (FCS) is a user level interface to Files-ll. 
Its principal feature is a record control facility that allows 
sequential processing of variable length records and sequential and 
random access to fixed length record files. FCS interfaces to the 
Virtual block facility provided by the basic Files-1l structure. 


C.5.1 FCS File Attributes 


FCS stores attribute information about the file in the file's user 
attribute area (H.UFAT - see earlier discussion). It uses only the 
first 7 words. The rest are ignored by FCS, but are reserved by DEC. 
(RMS uses an additional 3 words, 10 words in all, for relative and 
indexed file attributes.) The following items are contained in the 
attribute area. They are identified by the usual symbolic offsets 
(relative to the start of the attribute area). The offsets may be 
defined in assembly language programs’ by calling and invoking the 
macro FDOFFS DEFSL. Flag values and bits may be defined by calling 
and invoking the macro FCSBTS$. These macros are in the system macro 
library of any operating system that Supports Files-ll. 
Alternatively, all these values are defined in the system object 
library of any system that supports Files-ll, and may be obtained at 
link time. 


FCS FILE STRUCTURE 


C.5.1.1 F.RTYP: 1 Byte — Record Type - This byte identifies which 
type of records are contained in this file. The following three 
values are legal: 


R.FIX Fixed length records. 
R.VAR Variable length records. 
R.SEQ Sequenced Variable Length records 


F.RATT: 1 Byte - Record Attributes 


This byte contains record attribute bits that control the handling of 
records under various contexts. The following flag bits are defined: 


FD.FTN Use Fortran carriage control if set. 
The first: byte of each record is to be 


interpreted as a standard Fortran 
carriage control character when the 
record is copied to a carriage control 
device. 


FD.CR Use implied carriage control if set. 
When the file is copied to a carriage 
control device, each record is to be 
preceded by a line feed and followed by 
a carriage return. Note that the FD.FTN 
and FD.CR bits are mutually excluSive. 


FD.PRN Used to indicate that the two byte 
sequence number field for R.SEQ record 
format is to be interpreted as print 
control information. See later in this 
appendix for format of print information. 


FD.BLK Records do not cross block boundaries if 
| set. Generally, there will be dead 
space at the end of each block. How 
this is handled is explained in the 
description of record formats in Section 

Ea D2 < | 


C.5.1.2 F.RSIZ: 2 Bytes - Record Size - In a fixed length record 
file, this word contains the size of the records in bytes. Ina 
variable or sequenced variable length record file, this word contains 
the size in bytes of the longest record in the file. 
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C.5.1.3 F.HIBK: 4 Bytes - Highest VBN Allocated - This 32 bit number 
is a count of the number of virtual blocks allocated to the file. 
Since this value is maintained by FCS, it is usually correct, but it 
is not guaranteed since FCS is a user level package. 


C.5.1.4 F.EFBK: 4 Bytes - End of File Block - This 32 bit number is 
the VBN in which the end of file is located. Both F.HIBK and F.EFBK 
are stored with the high order half in the first two bytes, followed 
by the low order half. 


C.5.1.5 F.FFBY: 2 Bytes - First Free Byte - This word is a count of 
the number of bytes in use in the virtual block containing the end of 
file. In other words, it is the offset to the first byte of the file 
available for appending. Note that an end of file that falls on a 
block boundary may be represented in either of two ways. If the file 
contains precisely n blocks, F.EFBK may contain n and F.FFBY will 
contain 512, or F.EFBK may contain n+l and F.FFBY will contain 0. 


C.5.1.6 S.FATT: 14 Bytes - Size of Attribute Block - This’ symbol 
represents the total number of bytes in the FCS file attribute block. 


C.5.1.7 FCS File Attributes Layout - 


F.RATT Record Attr. Record Type F.RTYP 
ee Record Size (Bytes) | ~—*||_—s*#F«RSIZ 
— Highest VEN =——(<i‘éOé*dSCS#CO«SHIBK 
Allocated 7 
end of File” F .EFBK 
- VBN 7 
"First Free Byte” F.FFBY 
~-~------------------------------------ S.FATT 


FCS FILE STRUCTURE 


C.5.2 Record Structure 


This section describes how records are packed in the virtual blocks of 
a disk file. In general, FCS treats a disk file as a sequentially 
numbered array of bytes. Records are numbered consecutively starting 
with l. 


C.5.2.1 Fixed Length Records - In a file consisting of fixed length 
records, the records are simply packed end to end with no additional 
control information. If the record length is odd, each record is 
padded with a single byte. The content of the pad byte is undefined. 
For direct access, the address of a record is computed as follows: 


Let: n = record number 
k = record size (in bytes) 
m = byte address of record in file 
q = number of records per block 
j} = VBN containing the start of the record 
i = byte offset within VBN j 
then h = ((k+1)/2)2 (rounded up record length) 
m= (n-l)h 
j = m/512+1 (truncated) 
i = m mod 512 


The previous discussion assumes that records cross’ block boundaries 
(that is, FD.BLK is not’ set). If records do not cross block 
boundaries, they are limited to 512 bytes, and the following equations 
apply (the variables are defined as above): 


h = ((k+1)/2)2 (rounded up record length) 
q = 512/k (truncated) 

j = (n-1)/qgtl (truncated) 

i = ((n-1) mod q)h 


C.5.2.2 Variable Length Records - In a file consisting of variable 
length records, records may be up to 32767 bytes in length. Each 
record is preceded by a two byte binary count of the bytes in _ the 
record (the count does not include itself). For example, a null 
record is represented by a single zero word. The byte count is always 
word aligned. For example,if a record ends on an odd byte boundary, 
it is padded with a single byte. The content of the pad byte is 
undefined. 


FCS FILE STRUCTURE 


If records do not cross block boundaries (FD.BLK is set), they are 
limited to a size of 510 bytes. A byte count of -1 is used as a flag 
to signal that there are no more records ina particular block. The 
remainder of that block is then dead space and the next record in the 
file starts at the beginning of the next block. 


C.5.2.3 Sequenced Variable Length Records - The format of a sequenced 
file is identical to a variable length record file except that a two 
byte sequence number field is located immediately after the byte count 
field of each record. This field contains a binary value which is 
usually interpreted as the line number of that record (see F.RATT, 
FD.PRN and Section C.5.2.3.1. The sequence number is not returned as 
part of the data when a record is read, but is available separately. 
Note that the record byte count field counts the sequence number field 
as well as the data of the record. 


Format of Two Byte Print Control Field in R.SEQ Records - If the 
FD.PRN bit is set in the record attribute then the two byte "sequence 
number" field is used to contain carriage control data for the record. 
Byte 0 is print control information to act upon before the record data 
is output to a unit record device. Byte 1 is print control 
information to act upon after the record data has been output to a 
unit record device. 


The format of each byte is as follows: 


Bit 7 Bits 6-0 Meaning 
0 0 No carriage control 
0 count(1-127) "count" new lines (CR/LF) 
Bit 7 Bit 6 Bit 5 Bits 4-0 Meaning 
1 0 0 ASCII CO set ASCII char to 
output (CR,FF etc.) 
1 0 1 ASCII Cl set ASCII char (8 bit code) 
| to output 
1 1 0 CODE (0-63) Device specific code 
1 1 1 - Reserved 


NOTE 


The print control field is not currently supported by 
FCS or RMS-1ll. 
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FILES-11 QIO INTERFACE TO THE ACPS 


This appendix describes the QIO level interface to the file processors 
include Fl1ACP for Files-1l disks and MTAACP for ANSI 


(ACPs). These 
magnetic tape. 


FIIACP supports the following functions: 


IO.CRE 
IO.DEL 
IO.ACR 
IO.ACW 
IQ.ACE 
ITO.DAC 
IO.EXT 
IQO.RAT 
IO.WAT 
IO.FNA 
IO.RNA 
IO.ENA 
IO.ULK 


Create 
Delete 
Access 
Access 
Access 


file 

file 

file for read only 

file for read/write 

file for read/write/extend 


Deaccess file 


Extend 


file 


Read file attributes 
Write file attributes 
Find file name in directory 


Remove 


file name from directory 


Enter file name in directory 
Unlock block 


D.-1 QIO PARAMETER LIST FORMAT 


The device-independent part of a file processing QIO parameter list is 
all other QIO parameter lists. The file processor QIOs 
require the following six additional words in the parameter lists: 


identical to 


Parameter 
Parameter 
Parameter 


Parameter 


Word 1 Address of a 3-word block containing the 
file identifier 

Word 2 Address of the attribute list 

Words 3 & 4 Size and extend control information 

Word 5 Window size information and access 


control 
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Parameter word 6 Address of the file name block 


NOTE 
The P/OS Executive treats File 


Identifier Blocks, filename blocks, and 
attribute list entries as read/write 
data. For this reason, they may not be 
used in read-only code segments OF 
libraries. 


D.l1.1 File Identification Block 


The File Identification Block is a 3-word block containing the file 
number and the file sequence number. The format of the File 
Identification Block is as follows: 


FIIACP uses the file number as an index to the file header in the 
index file. Each time a header block is used for a new file, the file 
sequence number is incremented. This insures that the file header is 
always unique. The third word is not currently used but is reserved 
for the future. 


D.1.2 The Attribute List 


The file attribute list controls FIlI1ACP reads or writes. File 
attributes are fields in the file header, described later in this 
appendix. 


The attribute list contains a variable number of entries terminated by 
an all-0O byte. The maximum number of entries in the attribute list is 
S1X. 


An entry in the attribute list has the following format: 


-BYTE <Attribute type>, Attribute size 
~-WORD Pointer to the attribute buffer 
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D.1.2.1 The Attribute Type - This field identifies the individual 
attribute to be read or written. The sign of the attribute type code 
determines whether the transfer is a read or write operation. If the 
type code is negative, the ACP reads the attribute into the buffer. 
If the type code is positive, the ACP writes the attribute to the file 
header. Note that the sign of the type code must agree with the 
direction implied by the operation. For example, if the type code is 
positive, the operation must be an IO.WAT or I0O.DAC. 


The attribute type is one of the following: 


@ File owner (H.FOWN) 


The file owner UIC is a binary word. The low byte is_ the 
owner number and the high byte is the group number. 


@® File protection (H.FPRO) 


The file protection word is a bit mask with the following 
format: 


Each of the fields contains four bits, as follows: 


Bit l1 Read Access 

Bit 2 Write Access 
Bit 3 Extend Access 
Bit 4 Delete Access 


e File characteristics (H.UCHA) 


The following user characteristics are currently contained in 
the l-byte H.UCHA field: 


UC.CON = 200 Logically contiguous file 
UC.DLK = 100 File improperly closed 


@ Record I/O Area (U.UFAT) 
This field contains a copy of the first seven* words of the 
file descriptor block. 


@® File name (I.FNAM) 
The file name is stored as nine Radix-50 characters. the 
fourth word of this block contains the file type and the fifth 
word contains the version number. 


@e File type (I.FTYP) 
The file type is stored as three Radix-50 characters. 


@® Version number (I.FVER) 


1. RMS uses 32 bytes. The first seven are compatible with FCS _ for 
sequential files. 
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The version number is stored as a binary number. 


@® Expiration date (I.EXDT) 

Creation date (I.CRDT) 

Revision date (I.RVDT) 

The expiration date is currently unused. When the file is 
created, the ACP initializes the creation date to the current 
date and time. It initializes the expiration and revision 
dates to 0. The ACP sets the revision date to the current 
date and time each time the file is deaccessed. 


@® Statistics block 
This block is described later in this appendix. 


@® Read entire file header 
This buffer is assumed to be 1000 blocks’ long. You cannot 
write this attribute. 


@® Revision number (I.RVNO) 
The ACP sets the revision number to 0, and increments it every 
time the file is deaccessed. 


@ Placement Control 


D.1.2.2 Attribute Size - This word specifies the number of bytes of 
the attribute to be transferred. Legal values are from 1 to the 
maximum size of the particular attribute. Table D-1 shows the maximum 
size for each attribute type. 


Table D-l: Maximum Size for Each File Attribute 


8 


Maximum 

Attribute Attribute Attribute Size 
Type Code Type in Octal Bytes 

1 File owner 6 

2 Protection 4 

3 File characteristics 2 

4 Record I/O area 40 

5 File name,type,version number 12 
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6 File type 4 
7 Version number 2 
10 Expiration date 7 
Lt Statistics block 12 
12 Entire file header 0 
13 Block Size (magtape only) = 
15 Revision number and 
creation/revision/expiration dates 43 
16 Placement control 16 


D.1.2.3 Attribute Buffer Address - The attribute Buffer Address 
field contains the address of the buffer in the user's task space to 
or from which the attribute is to be transferred. 


D.1.3 Size and Extend Control 


These two parameters specify how many blocks the file processor 
allocated to a new file or adds to an existing file. These 
parameters also control the type of block allocation. 


The format is as follows: 


-BYTE <High 8 bits of size>, <extend control> 
eWORD <Low 16 bits of size> 


The size field specifies the number of blocks to be allocated to a 
file on I0O.CRE and I0O.EXT operations, and the final file size on 
IO.DEL operations. 


The extend control field controls the manner in which ane extend 
operation is to be done. The following bits are defined: 


EX.AC1=1 The extend size is to be added as a contiguous 
block. 
EX .AC2=2 Extend by the largest available contiguous piece 


up to the specified size. 


EX.FCO=4 The file must end up contiguous. 


QIO PARAMETER LIST FORMAT 


EX. ADF=10 Use the default rather than the specified size. 
The default extend size is the size that was 
specified when the volume was mounted. 


EX .ALL=20 Placement control (see Section D.2. 


EX. ENA=200 Enable extend. 


D.1.4 Window Size and Access Control 


This parameter specifies the window size and access control 
information in the following format: 


~-BYTE <window size>, <access control> 


This word is only processed if the high bit of the access’ control 
byte (AC.ENB) is set. 


Window size is the number of mapping entries. Specifying a negative 
window size minimizes window turns. If this byte is zero, the file 
processor uses the volume default. The size of the window allocated 
in the dynamic storage region is 6 times the number of mapping 
entries (each mapping entry is 3 words), plus 10 bytes for the 
window control block. The mapping entries are allocated in 
secondary pool. The window control block and a pointer to secondary 
pool are located in primary pool. 


The following access control bits are defined: 


AC.LCK=1 Lock out further accesses for Write or Extend 
AC.DLK=2 Enable Deaccess lock 
The deaccess lock sets the lock bit in the file 
header if the file is deaccessed as the result of a 
task exit without explicitly deaccessing the file. 
The lock bit is set by the executive. The lock bit 
is not set when the system crashes. 


AC.LKL=4 Enable block locking 
AC.EXL=10 Enable explicit block unlocking 
AC .WCK=40 Initiate driver write-checking 


AC.ENB=200 Enable Access 


NOTE 


Both AC.LKL and AC.EXL must be set if 
you want block locking. If you do not 
want block locking, both bits must _ be 
clear. Any other combination is-~ an 
error. 
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D.1.5 File Name Block Pointer 


This word contains the address of a 15-word block in the issuing 


task'sS space. This block is called the file name block. The file 
name block is described in detail later in this appendix. 


The fields of the file name block that are particularly important in 
file-processing operations are: 


® Directory identification (N.DID) 
This field is required for all disk operations. It specifies 


the directory to which the operation applies. This field is 
not used for tape operations. 


® File identification (N.FID) 


This field is required as input for enter operations. This 
field is returned as output by find and remove operations. 


@ File name (N.FNAM), type (N.FTYP), and version number (N.FVER) 
These fields are required as input to enter, find, and remove 
operations. For find and remove operations, the file 
processor locates the appropriate entry by matching the 
information in these fields with the directory entries. 


® Status word (N.STAT) 


@® Wildcard context (N.NEXT) 
This field is required as input for wildcard operations. Tt 
specifies the point at which to resume processing. It is 
updated for the next operation. It must initially be set to 
0. 


D.2 PLACEMENT CONTROL 


The placement control attribute list entry controls the placement of a 
file in a particular place on the disk. You can specify either exact 
Or approximate placement on IO.CRE and IO.EXT operations. 


The placement control entry must be the first entry in the attribute 
list. 


The format of the placement control attribute list entry is as 
follows: 


~-BYTE placement control,0 

eWORD high-order bits of VBN or LBN 

~WORK low-order bits of VBN or LBN 

~-BLKW 4 > Buffer to receive starting and ending LBN if 
AL.LBN is set. 
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The following bits are defined for the placement control field: 


AL. VBN=1 Set if block specified is a VBN;: otherwise, the 
block is the LBN 

AL.APX=2 Set if you want approximate placement; 
otherwise, placement is exact 

AL.LBN=4 Set if you want starting and ending LBN information 


D.3 BLOCK LOCKING 


Block locking only occurs when the user accesses a file with AC.LKL 
and AC.EXL set in the access control byte of the parameter list. Any 
read or write operation causes a check to see if the block is locked. 


A write access locks a block for exclusive access. A write operation 
can only access a block that is not locked by any accessor. The only 
exception to this is an exact match with a previous lock owned by the 
Same accessor. 


A read access locks a block for shared access. A read operation can 
access any block locked for shared access. 


The user must unlock a block with an explicit unlock request, IO.ULK. 
IO.ULK may be used to unlock one or all blocks. 


If all accessors to a file have not requested block locking, the ACP 
returns an error. 


When the file is deaccessed, all locks owned by the accessor are 
released. 


Each active lock requires eight bytes from the dynamic storage region. 
This storage is deallocated when the file is deaccessed. 


D.4 SUMMARY OF F1I1ACP FUNCTIONS 


The following is a summary of the functions implemented in FIIACP. A 
list of accepted parameters follows each function. All parameters are 
required unless specified as optional. Parameters other than those 
listed are illegal for that function and must be 0. 


IO.CRE Create file 


# 1 The file identifier block is filled in with the file 
identifier and sequence number of the created file. 


#2 Write Attribute and/or Placement Control list 
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IO.DEL 


IO.ACR 


IO.ACW 


IO.ACE 


TO.DAC 


IO.EAT 


I0O.RAT 


#3 & #4 


#5 


# 1 
#3 


# 1 
# 2 
#5 


# 1 


# 2 


#9 


# 1 


#2 


#3 


# 1 


& 


& 


# 4 


# 4 


SUMMARY OF FIIACP FUNCTIONS 


(optional) 

Extend Control (optional) 

The amount allocated to the file is returned in the 
high byte of IOST(1) plus IOST(2). 

May be nonzero but must be disabled 

Delete or truncate file 


Optional if the file is accessed 


Size to truncate the file to. If not enabled, the 
file is deleted. If enabled, the remaining 31 bits 
specify the size the file is to be after truncation. 
The change in file allocation is returned in the high 
byte of IOST(1) plus IOST(2). This amount will be 
zero or negative. 

Access file for read only 

Access file for read/write 

Access file for read/write/extend 

File identifier pointer 

Read attributes control (optional) 

Access control must be enabled 

Deaccess file 

File identifier pointer (optional) 

Write attributes control list 

May be nonzero but must be disabled 

Extend file 

Optional if file is accessed 

Placement control attribute list (optional) 

Extend control 

The amount allocated to the file is returned in the 
high byte of IOST(1) plus IOST(2). 


Read attributes 


Optional if file is accessed 
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#2 Read attributes control list 
IO.FNA Find name in directory 
IO.RNA Remove name from directory 
IO.ENA Enter name in directory 
#5 May be nonzero but must be disabled 
#6 File nate block pointer 
TO.ULK Unlock block 
#2 QO or count of blocks to unlock 


#4 & #5 Starting VBN to unlock or 0 to unlock all blocks. 


IO.RVB Read virtual block 
IO.WVB Write virtual block 
#1 User buffer 

#2 Buffer length 


#4 & #5 VBN 


D.5 HOW TO USE THE ACP QIOS 


Although the operations described in this section are normally 

performed by the file-access methods (RMS and FCS), your application 

may issue the ACP QIOs. The required parameters for each QIO are 

described above. The necessary steps for common operations follow. 
NOTE 


The file identifier is the only way to refer to a 
File. 


D.5.1 Creating a File 
To create a file: 
@® Use IO.CRE to create it. 


@ Enter it in the Master File Directory (MFD) or aeuser 
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directory with IO.ENA. 


D.5.2 Opening a File 
To open a file: 


@ Use IO.FNA to find the File Identifier 
MFD. 


@® Use IO.FNA to find the File Identifier 
directory. 


of the directory in the 


of the file in 


@® Access the file with IO.ACR, IO.ACW, or IO.ACE. 


D.5.3 Closing a File 
To close a file: 


@® Deaccess the file with IO.DAC. 


D.5.4 Extending a File 
To extend a file: 


@® Use IO.FNA to find the file identifier 
accessed. 


® Use IO.EXT to extend the file. 


D.5.5 Deleting a File 


To delete a file: 


® Use IO.FNA to find the file identifier. 


if the file is 


@e Use IO.RNA to remove the directory name. 


@e® Use IO.DEL to delete the file. 
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D.6 FILE HEADER BLOCK FORMAT 


Table D-2 shows the format of the file 
areas within the file header 
following sections. 
defined either 
statements: 


header block. 


locally or globally, as 


FHDOFS DEFSL *DEFINE OFFSETS LOCALLY. 
FHDOFS DEFSG *DEFINE OFFSETS GLOBALLY. 
Table D-2: File Header Block 
Area Size Content 
(in Bytes) 
Header Area l Identification area offset 
in words 
1 Map area offset in words 
2 File number 
2 File sequence number 
number 
= Offset to file owner 
information, consisting of 
member number and group 
number 
1 Member number 
1 Group number 
2 File protection code 
l User-controlled file 
characteristics 
1 System-controlled file 
characteristics 
32; User file attributes 
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various 
block are described in detail in the 
The offset names in the file header block may be 


shown in the _ following 


Offset 


H.ITDOF 


H.MPOF 
H.FNUM 


H.FSEQ 


H. FOWN 


H.PROG 
H.PROJ 
Hef PRO 


H.UCHA 


H.SCHA 


H.UFAT 


Identification 
Area 


Map Area 


FILE HEADER BLOCK FORMAT 


Size in bytes of header 
area of file header block 
File name (Radix-50) 

File type (Radix-50) 


File version number 
(binary) 


Revision number 
Revision date 
Revision time 
Creation date 
Creation time 
Expiration date 


To round up to word 
boundary 


Size (in bytes) of 
identification area of 
file header block 


Extension segment number 


Extension relative volume 
number (not implemented) 


Extension file number 


Extension file sequence 
number 


Size (in bytes) of the 
block count field of a 


retrieval pointer (1 or 2); 


only 1 is used 


Size (in bytes) of the 


logical block number field 
of a retrieval pointer (2, 


3, or 4); only 3 is used 
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I.FNAM 
lek TYP 


I.FVER 


I.RVNO 
I.RVDT 
I.RVTI 
I.CRDT 
I.CRTI 


I.EXDT 


S.IDHD 


M.ESON 


M.ERVN 


M.EFNU 


M.EFSO 


M.CTSZ 


M.LBSZ 


Checksum Word 


D.6.1 Header Area 


The information in the 
of the following: 


Identification area - 
offset 


Map area offset = 


File number _ 


File sequence number - 


FILE HEADER BLOCK FORMAT 


Words of retrieval pointers M.USE 
in use in the map area 


Maximum number of words M.MAX 
of retrieval pointers 
available in the map area 


- Start of retrieval pointers M.RTRV 


Size in bytes of map area S .MPHD 
of file header block 


Checksum of words 0 through H.CKSM 
255 


NOTE 


The checksum word is the last word of the 
file header block. Retrieval pointers 
occupy the space from the end of the map 
area to the checksum word. 


header area of the file header block consists 


Word 0, Bits 0-7. This byte locates the start 
of the identification area relative to the 
start of the file header block. This offset 
contains the number of words from the start of 
the header to the identification area. 


Word 0, Bits 8-15. This byte locates the start 
of the map area relative to the start of the 
file header block. This offset contains’ the 
number of words from the start of the header 
area to the map area. 


The file number defines the position this’ file 
header block occupies in the index file; for 
example, the index file is number 1, the 
storage bit map is file number 2, and so forth. 


The file number and the file sequence number 
constitute the file identification number used 
by the system. This number is different each 
time a header is reused. 
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Structure level 


File owner 
information 


File protection code 


File characteristics 


User file 
attributes 
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This word identifies the system that created 
the file and indicates the file structure. A 
value of [1,1] is associated with all current 
FILES-11l volumes. 


This word contains the group number and owner 
number constituting the User Identification 
Code (UIC) for the file. Legal UICS are within 
the range [1,1] to [377,377]. UIC [1,1] is 
reserved for the system. 


This word specifies the manner in which the 
file can be used and who can use it. When 


creating the file, you specify the extent of 
protection desired for the file. 


This word, consisting of two bytes, defines the 
status of the file. 


Byte 0 defines the user-controlled characteris- 
tics, as follows: 


UC.CON = 200 - Logically contiguous file. 
When the file is extended (for example, by a 
WRITE or PUT), bit UC.CON is cleared whether 
or not the extension requests contiguous 
blocks. 


UC.DLK = 100 - File improperly closed. 


Byte 1 defines system-controlled characteris- 
tics, as follows: 


SC.MDL = 200 - File marked for delete 


SC.BAD 100 - Bad data block in file 

This area consists of 16 words. The first 
seven words of this area are a direct image of 
the first seven words of the FDB when the file 
is opened. The other nine words of the record 
I/O control area are not used by FCS, although 
RMS does use them. 


D.6.2 Identification Area 


The information in the identification area of the file header block 
consists of the following: 
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File name - The file’s creator specifies a file name of up 
to mine Radix-50 characters in length. This 
name is placed in the name field. The unused 
portion of the field (if any) is zero-filled. 


File type - This word contains the file type in Radix-50 
format. 

File version number - This word contains the file version number, in 
binary, as specified by the creator of the 
file. 

Revision number - This word is initialized to 0 when the file is 


created: it is incremented each time a file is 
closed after being updated or modified. 


Revision date - Seven bytes are used to maintain the date on 
which the file was last revised. The revision 
date is kept in ASCII form in the format day, 
month, year (two bytes, three bytes, and two 
bytes, respectively). This date is meaningful 
only if the revision number is a nonzero value. 


Revision time - Six bytes are used to record the time at which 
the file was last revised. This information is 
recorded in ASCII form in the format hour, 
minute, and second (two bytes each). 


Creation date - The date on which the file was created is kept 
in a 7-byte field having the same format as 
that of the revision date (see above). 


Creation time - The time of the file's creation 1S maintained 
in a 6-byte field having the same format as 
that of the revision time (see above). 


Expiration date - The date on which the file becomes eligible to 
be deleted is kept in a 7-byte field having the 
same format as that of the revision date (see 
above). Use of expiration is not implemented. 


D.6.3 Map Area 


The map area contains the information necessary to map virtual block 
numbers to logical block numbers. This is done by means of pointers, 
each of which points to an area of contiguous’ blocks. A pointer 
consists of a count field and a number field. The count field defines 
the number of blocks contained in the contiguous area pointed to, and 
the logical block number (LBN) field defines the block number of the 
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first logical block in the area. 


A value of n in the count field (following) means that n+l blocks’ are 
allocated, starting at the specified block number. 


The retrieval pointer format used in the FILES-11 file structure is as 
follows: 


15 


0 
COUNT-1 HIGH LBN 


LOW LBN 


ZK-303-81 


The map area normally has space for 102 retrieval pointers. It can 
map up to 102 discontiguous segments or up to 26112 blocks if the file 
is contiguous. If more retrieval pointers are required because the 
File is too large or consists of too many discontiguous segments, 
extension headers are allocated to hold additional retrieval pointers. 
Extension headers are allocated within the index file. They are 
identified by a file number and a file sequence as are other file 


headers; however, extension file headers do not appear in any 
directory. 


A nonzero value in the extension file number field of the map. area 
indicates that an extension header exists. The extension header is 
identified by the extension file number and the extension file 
sequence number. The extension segment number is used to number the 
headers of the file sequentially, starting with a 0 for the first. 


Extension headers of a file contain a header area and identification 
area that are a copy of the first header as it appeared when the first 
extension was created. Extension headers are not updated when the 
first header of the file is modified. 


Extension headers are created and handled by the file control 
primitives as needed; their use is transparent to you. 


D./ STATISTICS BLOCK 


The format of the statistics block is shown in Table D-3 _ below. The 
statistics block is allocated manually in your program. 
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Table D-3: Statistics Block Format 
Word QO HIGH LOGICAL BLOCK NUMBER 


(O if file is noncontiguous) 


Word 1 LOW LOGICAL BLOCK NUMBER 


(O if file is noncontiguous) 


Word 2 SIZE (high) 
Word 3 SIZE (low) 
Word 4 LOCK COUNT ACCESS COUNT 


D.8 ERRORS RETURNED BY THE FILE PROCESSORS 


The error codes returned by F11lACP and MTAACP are shown in Table D-4. 


Table D-4: File Processor Error Codes 


Error 
Code Operations Explanation 


IF.ABO IO.RVB/IO.WVB Indicates that all 
requested data was not 


transferred by the 
device. 


IE.ALC Extend or create operation Indicates that the 
operation failed to 
allocate the file based 
on placement control or 
because of other related 
problems. 


IE.ALN An attempt to access a file Indicates that a file is 
already accessed on that 
LUN. 
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IE.BAD Any function 


IE.BDR 


IE.BHD 


IE.BVR 


IE.BYT 


IE.BTP 


ITE.CKS 


IE.CLO 


Directory operations 


Any operation 


Directory operations 


Any function 


Unlabeled Magtape Create 


Any operation 


File access operations 
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Indicates that a required 
parameter is missing, 
that a parameter that 
must not be present is 
present, that a parameter 
that must be disabled is 
enabled, or that a 
parameter value is 
invalid. 


Indicates that you 
attempted a directory 
operation ona file that 
is not a directory, or 
that the specified 
directory is corrupted. 
This is usually caused by 
a 0 version number field. 


Indicates that a corrupt 
file header was 
encountered, or that the 
operation required a 
feature not supported by 
the FCP (such as 
multiheader support or 
Support for unimplemented 
features). 


Indicates that you 
attempted to enter a name 
in a directory with a 
negative or 0 version 
number. 


This error is returned if 
the buffer specified is 
on an odd byte boundary 
or is not a multiple of 
four bytes. 


An attempt was made to 
create an unlabeled tape 
file with a record type 
other than fixed. 


Indicates that the 
checksum of a file header 
is incorrect. 


Indicates that the file 


IE.DFU 


IE.DUP 


IE.EOF 


IE.HFU 


IE«IFC 


IE.IFU 


ITE.LCK 
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An allocation request 


An enter name operation 


IO.RVB/1IO.WVB/I10. DEL 


An extended operation 


Returned by exec 


Create or extend operation 


Returned on file access, 
directory operations, and 
on truncate 
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was locked against access 
by the "“deaccess lock 
bits 


Indicates that there is 
insufficient free disk 
Space for the requested 
allocation. 


Indicates that the name 
and version already 
exist. 


On read operations, this 
indicates an attempt to 
read beyond end of file. 
On truncate operations, 
it indicates an attempt 
to truncate a file to a 
length longer than that 
allocated or that the 
file was already at EOF. 


Indicates that the file 
header is full and cannot 
contain any more 
retrieval pointers and 
that adding an extension 
header is not allowed. 
When this is returned on 
a create operation, it 
indicates that the index 
file could not be 
extended to allow a file 
header to be allocated. 


Tllegal function code. 


Indicates that there are 
no file headers available 
based on the parameters 
specified when the volume 
was initialized. 


Indicates that the file 
is already accessed by a 
writer and that shared 
write has not been 
requested or is not 
allowed. 


ITE.LUN 


ITE .NOD 


IE.NSF 


IE.OFL 


IE.PRI 


IE.RER 


IE.~SNC 
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Any operation requiring 
a file ID 


All file operations 
that require DSR 


All file operations 


Returned by exec 


Any operation 


Any operation 


Any operation 
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Indicates that file ID 
has not been supplied and 
that the file is not 
accessed on the LUN. 


Indicates that an I/O 
request failed due to 
IE.-UPN, that the FCP was 
unable to allocate 
required space from DSR 
or from secondary pool 
for data structures. 


Indicates that the 
specified directory entry 
does not exist, that a 
file corresponding to the 
file ID does not exist, 
or that the file is 
marked for delete. 


The device is off line. 


Indicates that the user 
does not have the 
required privilege for 
the requested operation, 
or that the user has not 
requested the proper 
access to the file if the 
file is already accessed 
(for example, an attempt 
to write to a file that 
is accessed for read). 
This also indicates an 
attempt to do file I/O to 
a device that is not 
mounted. 


Indicates that the FCP 
encountered a fatal 
device read error during 
an operation; the 
operation has been 
aborted. 


Indicates that the file 
number and the value 
contained in the header 
do not agree. This 
generally means that the 


FRRORS RETURNED BY THE FILE PROCESSORS 


header has gone bad due 
to a crash or a hardware 


error. 

IE.SPC Returned by exec Indicates an illegal 
buffer. 

IE.SQC Any operation Indicates that the file 


sequence number does not 
agree with the file 
header; usually indicates 
that the file has been 
deleted and the header 
has been reused. 


IE.WAC File access operations Indicates that the file 
is already write accessed 
and lock against writers 
is requested. 


IE.WAT Write attributes Indicates that the FCP 

and deaccess encountered an invalid 
attribute. 

IE.WER Any operation Indicates that the FCP 


encountered a fatal 
device write error during 
an operation. The 
operation has been 
aborted but the disk 
structure may have been 
corrupted. 


IE.WLK Any operation Indicates that the volume 
requiring write access is software write-locked. 


D.9 FILENAME BLOCK 


The format of a filename block is illustrated in Figure D-l. The 
offsets within the filename block are described in Table D-5. 


The offset names in a filename block may be defined either locally or 
globally, as follows: 


NBOFSL ;DEFINE OFFSETS LOCALLY. 
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NBOFFS DEFSL ;DEFINE OFFSETS LOCALLY. 
NBOFFS DEFSG *>DEFINE OFFSETS GLOBALLY. 
NOTE 
When you are referring to filename block 


locations, it is essential to use the symbolic 
offset names, rather than the actual addresses of 
such locations. The position of information 
within the filename block may be subject to change 
from release to release, whereas the offset names 
remain constant. 


Table D-5: Filename Block Offset Definitions 


Offset 


N.FID 


N.FNAM 


N.FTYP 


N.FVER 


N.STAT 


N.NEXT 


N.DID 


N.DVNM 


NUNIT 


nine 


three 


bit 


Size 
(in Bytes) Contents 

6 File identification field 

6 File name field; specified as 
characters that are stored in Radix-50 
format 7 

2 File type field; specified as 
characters that are stored in Radix-50 
format 

2 File version number field (binary) 

2 Filename block status word (See 
definitions in Table D-6.) 

2 Context for next .FIND operation 

6 Directory identification field 

2 ASCII device name field 

2 Unit number field (binary) 


The bit definitions of the filename block status word (N.STAT) in the 
FDB and their significance are described in Table D-6. 
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Symbols marked with an asterisk (*) in Table D-6 indicate bits that 
are set if the associated information is supplied through an ASCII 
dataset descriptor. 


CUMULATIVE 
LENGTH IN 
BYTES (OCTAL) 


Figure D-l: Filename Block Format 


Table D-6: Filename Block Status Word (N.STAT) 


Value 

Symbol (in Octal) Meaning 

NB.VER* | Set if explicit file version number is 
specified 

NB.TYP* 2 Set if explicit file type is specified 

NB .NAM* 4 Set if explicit file name is specified 

NB.SVR 10 Set if wildcard file version number is 
specified 

NB.STP 20 Set if wildcard file type is specified 
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NB.SNM 40 Set 1£ wildcard file name is specified 

NB.DIR* 100 Set if explicit directory string (UIC) is 
specified 

NB.DEV* 200 Set if explicit device name string is 
specified 

NB.SD1 400 Set if group portion of UIC contains 
wildcard specification* 

NB.SD2 1000 Set if owner portion of UIC contains 
wildcard specification* 

NB.ANS 2000 Set if file name is in ANSI format. 

1. Although NB.SD1 and NB.SD2 are defined, they are not set or 

supported by FCS. 

Table D-7: Filename Block Offset Definitions for ANSI Magnetic 

Tape 
Size 

Offset (in Bytes) Definition 

N.FID 2 File identification field 

N.ANM1] 12 First 12 bytes of ANSI filename string 

N.FVER 2 File version number field (binary) 

N.STAT 2 Filename block status word (See bit definitions 

in Table D-6. 

N.NEXT 2 Context for next .FIND operation 

N.ANM2 6 Remainder of the ANSI file name string 

N.DVNM 2 ASCII device name field 

N.UNIT 2 Unit number field (binary) 

The bit definitions of the filename block status word (N.STAT) are 


shown in Table D-6. 
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ABODFS, A-3 
ABODFS macro, A-4 
Acceptance routine, 1-14 
Accounting block offsets, 4-34 
Accumulation fields 
See ACNDFS 
SACHCK routine, 7-15 
SACHKB routine, 7-15 
ACNDFS, A-3 
ACP function, 2-16, 3-3 to 3-4, 
4-28 
ACP function mask, 4-25 to 4-27, 
4-31 to 4-33 
ACP QIOs 
usage, D-14 
Active Page Register 
see APR 
Address doubleword, 4-18 to 4-19, 
4-28, 4-45, 7-5, 7-1l 
Advanced driver features, 1-ll 
SALOCB routine, 7-16 
APR, 1-3, 1-8 


AST, 1-15 
Asynchronous System, Trap 
see AST 
-BR= 
Bitmap 


video, 9-l 
SBLKC1 routine, 7-13 
SBLKC2 routine, 7-13 
SBLKCK routine, 7-13, 7-23 
SBLXIO routine, 7-13, 7-19 
Buffer 
special user 
sample of driver handling, 
3-6, 4-38, 4-45 
Buffered I/O, 1-14, 4-7, 4-19, 
4-38, 4-73 
Bug Checking 
without XDT, 6-13 


-C=— 


Cancel I/0, 2-5 to 2-6, 4-37 
Checkpoint 
request, 3-5 
Checkpointing, 7-5 
CINTS directive, 1-1 
SCKBFB routine, 7-15, 7-20 
SCKBFI routine, 7-20 
SCKBFR routine, 7-20 
SCKBFW routine, 7-15, 7-20 
SCLINS routine, 7-22 
CLKDFS$, A-3 
CLKDFS macro, A-6 
Clock queue, 4-64, 4-66, 7-22 
control block, A-3 
CLUST.TSK, B-38 
Clustered libraries 
WRITE access, B-27 
CON task, 5-8 
Concurrent I/0, 1-7 
Configuration 
hardware, 2-8 
Contiguous KRB and SCB, 2-9, 4-52 
Control function mask, 4-25 to 
4-27 
Controller 
access, 2-3, 2-16, 4-61 
delayed, 2-16 
allowing parallel operations, 


2-3, 2-11 

configuration status for, 2-3, 
2-7 

defining type, 1-5, 2-1, 2-8 to 
2-9, 4-9 


group number, 1-8 

interrupt vector, 1-2, 1-7 to 
1-8, 4-6 

interrupts, 1-1, 1-9 

location of a CSR for a, 2-2 

maintaining hardware-specific 
information for, 2-2 

name, 2-1, 4-70, 5-6, 5-8 

number, 1-7 

request queue, 2-3, 2-16 

status, 2-16, 4-51, 4-74 

status change 
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INDEX 


Controller 

status change (Cont.) 
entry point, 4-74 

status extension 2, 
status extension 3, 
status word, 4-57 
table status byte, 4-65 

Controller Request Block 
See KRB 

Controller table 
see CTB 

CSR, 2-2, 4-53 
address, 4-59 
assignments 

setting, 1-15 

/CTB 
use in PROLOD, 

CTB 
definition, 1-5 
description, 2-9 
format, 2-2 
layout, 4-61 
overview, 2-1 
system list, 4-61 


4-52 
4-5] 
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use in handling interrupts, 2-2, 
2-16 
validation during PROLOD, 5-5 


CTB label, 4-4 

CTBDFS, A-3 

SCTLST, 2-1 
symbol, 2-17 


SCVBLN routine, 4-46 
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D.xxx offsets 
in DCB, 5-6 
Data base, 1-15, 
assembling, 4-3 
code, 4-66 
creating source code, 4-3 
CTB, 2-1 
details of structures, 4-1l 
driver; 2=5,. 1-7). 1-9, 1-15, 
2-4 
fork routine, l- 
global label, 4- 
SCTB, 4-4 
SDAT, 5-5 
SEND, 5-5 


4-3 


9 
3 . 


Data base (Cont.) 
labeling of data structures, 
4-3 
linked by DDT, 4-67 
loadable, 5-5 
module, 1-16 
overview of structures, 
programming 
requirements, 
shared access, 
structures 
augmented, 1-14 
composite arrangement, 
controllers and units, 
conventional, 1-14 
Executive, 1-6 
ordering of, 4-3 
typical arrangement, 2-9 
validation during PROLOD, 
Data structure 
definitions, A-1l 
Data structures 
I/O, 1-10 
shared system, 1-10 
Data transfer, 1-14 to 1-15 
SDCB 
global label, 
DCB 
ASCII device name, 4-23 
composite arrangement, 
creating mask words in, 
definition, 1-5 
details, 2-3, 4-22 
driver dispatch table, 
entry points, 2-3 
driver dispatch table pointer, 
2-14, 4-24 
driver-specific function masks, 
4-24 
establishing characteristics 
for, 2-3 
establishing I/O function masks, 
4-29 | 
fields, 
format, 4-22 
labeling, 4-3 
length of UCB, 2-4 
link to next DCB, 
list of, 2-3 
number of units stored, 
overview, 2-3 


2-1-2 
4-3 

3-6 

2-14 
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4-3 


2-14 
4-24 


Ban to 


4-23 


223 
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DCB (Cont.) 
pointer to first UCB, 2-4 
unit number range, 4-23 
validation during PROLOD, 5-5 
DCBDFS, A-1 
DCBDFS$ macro, A-8 
DDTS macro, A-10 
DDT$ macro call 
arguments of, 4-5 
placement of, 4-6 
SDEACB routine, 6-13, 7-24 
Deallocation entry point, 4-73 
Delayed controller access, 2-16 
SDEVHD routine, 2-3, 2-12 
Device 
address, l1-l 
busy, not busy, 1-13 
configured on-line, 1-15 
generic name, 2-3, 4-23 
interrupt, 1-1 to 1-2, 1-7, 
1-11 
registers, 1-1, 1-5, 4-38 
storage of static 
characteristics, 2-3, 4-22 
Device Control Block 
see DCB 
Device controller, 1-1 
busy, not busy, 1-13 
Device driver, 1-5 
See Driver 
Device interrupt address 
overview, 2-8 
Device interrupt vector, 2-5 
Device timeout 
entry point, 4-49, 4-73 
overview, 2-7 
Directive Parameter Block 
see DPB 
Disk 
geometry calculations, 4-46 
Doubleword 
address, 4-18 to 4-19, 4-28, 
7-11 
DPB 
details, 4-19 
format, 4-20 
I/O function allowances, 7-11 
usage in creating I/O packet, 
3-2 to 3-3 
DRDSP 


directive dispatcher, 3-2, 6-ll 
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Driver 


acceptance routine, 1-14 
accessing a controller, 2-2 
advanced features, 1-6 
assembling, 5-2 
code | 
details, 4-66 
standards, 4-1 
conversion routine, 4-26 
creating source code, 4-5 
data base, 1-5, 1-15 
linkages, 1-15 
data structure, 1-5, 2-12, 4-34 
accessing, 4-2 
details, 4-11 | 
DDT$ macro call, 4-5 
debugging, 6-1, 6-3 to 6-4 
using XDT, 6-l 
defining labels, 4-11, 4-67 
Driver Dispatch Table, 2-5 
address of routines, 1-5 
entry points, 2-14 
association of, 4-67 
format, 4-6/7 
generation of 
from DDTS, 4-67 
labels required, 4-67 
link to the driver code and 
data base, 4-67 
entry points, 4-5, 4-11, 4-70 
Executive services 
typically used, 3-5, 7-1 
for NPR devices on PDP-1ll, 7-1 
full duplex, 4-17 
full-duplex, 1-13 
handling multiple I/O requests, 
1-13 
I/O packet, 2-14 
I/O request 
processing, 1-5 
I/O requirements, 4-25 
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general functions, 4-5 distributing I/O requests, 1-5 
unloading, 5-3 handling 
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requirements, 4-66 information, 2-2 
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Files-1ll 
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SFORK1 routine, 7-26 to 7-27 
See also SFORK 
Full-duplex I/0O, 1-13 
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details, 4-26 
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ICB, 1-7, 4-64 
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contiguous with SCB, 2-4, 4-46 
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Nonexternal header, 6-6 
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See PDR 
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PCB, 2-12, 4-28 
PCBDFS, A-3 
PCBDFS$ macro, A-34 
PDP-11 
standard file structure, C-l 
PDP-11 Cluster Libraries, B-1l2 
PDR, 1-3 
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tracing fault, 6-4 
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PROLOD command, 1-15 to 1-16 
overview, 1-15 
PTBYT routine, 7-38 
SPTWRD, 7-39 
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OQOIO directive 
building I/O packet, 4-13 
creating DPB, 3-2 
directive dispatching, 3-2 
OIO Directive Parameter Block 
See QIO DPB, 3-2 
OIO DPB, 4-13, 4-19, 4-26, 7-l1l 
QIO parameter 
list format, D-2 
QIO request, 2-14 
OIOSYS macro, A-47 
SQUEBF routine, 1-14 to 1-15 
Queue optimization, 2-5 
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SRELOC, 7-41 
SRELOP routine, 7-13 
SREQU1 routine, 7-42 
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ROCNC, 4-58, 4-60 
ROCND, 4-58, 4-60 
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S.xxx offsets 
in SCB, 4-52 
SSAHDB, 6-9 
SSAHPT, 6-9, 6-12 
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pointer to first word of task 
: header, 6-6 
SCB, 1-5 
address for KRB, 2-4 
combined with KRB, 4-61 
composite arrangement, 2-15 
contiguous with KRB, 2-2, 4-4 
details, 4-46 
format, 4-5] 
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overview, 2-4 
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SCBDFS, A-3 
SCBDFS$S macro, A-58 
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1-9, 1l-ll, 2-15, 4-10, 4- 
4-44, 6-1 
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SHDDFS$, A-l, A-3 
Stack and register dump 
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System macro call, 4-5 
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